<?xml version='1.0' encoding="utf-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"../docbook-setup/docbookx/docbookx.dtd">
<!-- $Id: argomanual.xml 6 2008-09-28 20:23:13Z dthompson $ -->
<!--
Copyright (c) 1996-2008 The Regents of the University of California. All
Rights Reserved. Permission to use, copy, modify, and distribute this
software and its documentation without fee, and without a written
agreement is hereby granted, provided that the above copyright notice
and this paragraph appear in all copies.  This software program and
documentation are copyrighted by The Regents of the University of
California. The software program and documentation are supplied "AS
IS", without any accompanying services from The Regents. The Regents
does not warrant that the operation of the program will be
uninterrupted or error-free. The end-user understands that the program
was developed for research purposes and is advised not to rely
exclusively on the program for any reason.  IN NO EVENT SHALL THE
UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->


<book>

  <bookinfo>

    <date>5/17/2002</date>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/argologo200x190_on_ffffff.png" 
                format="PNG"/>
      </imageobject>
    </mediaobject>
    
    <title>ArgoUML User Manual</title>

    <subtitle>A tutorial and reference description</subtitle>

    <abstract>

      <para>This version of the manual is intended to describe the 
      version @VERSION@ of ArgoUML.</para>

    </abstract>

    <authorgroup>

      <author><firstname>Alejandro</firstname><surname>Ramirez</surname></author>

      <author><firstname>Philippe</firstname><surname>Vanpeperstraete</surname></author>

      <author><firstname>Andreas</firstname><surname>Rueckert</surname></author>

      <author><firstname>Kunle</firstname><surname>Odutola</surname></author>

      <author><firstname>Jeremy</firstname><surname>Bennett</surname></author>

      <author><firstname>Linus</firstname><surname>Tolke</surname></author>

      <author><firstname>Michiel</firstname><surname>van der 
      Wulp</surname></author>

    </authorgroup>

    <copyright>
      <year>2004</year>
      <year>2005</year>
      <year>2006</year>
      <year>2007</year>
      <year>2008</year>
      <holder>Michiel van der Wulp</holder>
    </copyright>
    <copyright><year>2003</year><holder>Linus Tolke</holder></copyright>
    <copyright><year>2001</year><year>2002</year><holder>Jeremy 
    Bennett</holder></copyright>
    <copyright><year>2001</year><holder>Kunle 
    Odutola</holder></copyright>
    <copyright><year>2000</year><holder>Philippe 
    Vanpeperstraete</holder></copyright>
    <copyright><year>2000</year><holder>Alejandro 
    Ramirez</holder></copyright>
    <copyright><year>2000</year><holder>Andreas 
    Rueckert</holder></copyright>
    <legalnotice>

      <para>This material may be distributed only subject to the terms 
      and conditions set forth in the Open Publication License, v1.0 or 
      later. A copy of this license is included in the section 
      <link linkend="app.legal">Open Publication License</link>. The 
      latest version is presently available at 
      <ulink url="http://www.opencontent.org/openpub/">
      http://www.opencontent.org/openpub/</ulink>.</para>

    </legalnotice>

  </bookinfo>

  <toc />
  <preface>

    <title>Preface</title>

    <indexterm><primary>Design</primary></indexterm>
    <para>Software design is a cognitively challenging task. Designers 
    must manually enter designs, but the primary difficulty is 
    decision-making rather than data-entry. If designers improved their 
    decision-making capabilities, it would result in better 
    designs.</para>

    <para>Current CASE tools provide automation and graphical user 
    interfaces that reduce the manual work of entering a design and 
    transforming a design into code. They aid designers in 
    decision-making mainly by providing visualization of design 
    diagrams and simple syntactic checks. Also many CASE tools provide 
    substantial benefits in the area of version control and concurrent 
    design mechanisms. One area of design support that has been not 
    been well supported is analysis of design decisions.</para>

    <para>Current CASE tools are usable in that they provide a GUI that 
    allows designers to access all the features provided by the tool. 
    And they support the design process in that they allow the designer 
    to enter diagrams in the style of popular design methodologies. But 
    they typically do not provide process support to guide the designer 
    through the design task. Instead, designers typically start with a 
    blank page and must remember to cover every aspect of the 
    design.</para>

    <para>

      ArgoUML is a domain-oriented design environment that provides 
      cognitive support of object-oriented design. ArgoUML provides 
      some of the same automation features of a commercial CASE tool, 
      but it focuses on features that support the cognitive needs of 
      designers. These cognitive needs are described by three cognitive 
      theories:
      <orderedlist>

        <listitem>

          <indexterm><primary>Reflection-in-Action</primary></indexterm>
          <para>reflection-in-action;</para>

        </listitem>

        <listitem>

          <indexterm><primary>Opportunistic Design</primary></indexterm>
          <para>opportunistic design; and</para>

        </listitem>

        <listitem>

          <indexterm><primary>Comprehension</primary></indexterm>
          <indexterm><primary>Problem Solving</primary></indexterm>
          <para>comprehension and problem solving.</para>

        </listitem>

      </orderedlist>

    </para>

    <para>ArgoUML is based directly on the UML 1.4 specification. The
    core model repository is an implementation of the Java Metadata
    Interface (JMI) which directly supports MOF and uses the
    machine readable version of the UML 1.4 specification provided
    by the OMG.</para>

    <para>Furthermore, it is our goal to provide comprehensive support 
    <indexterm><primary>XMI</primary></indexterm>
    for OCL (the Object Constraint Language) and XMI (the XML Model 
    Interchange format).</para>

    <para>ArgoUML was originally developed by a small group of people 
    as a research project. ArgoUML has many features that make it 
    special, but it does not implement all the features that commercial 
    CASE tools provide.</para>

    <para>The current version (@VERSION@) of ArgoUML implements all the 
    diagram types of the 
    
    <ulink url="http://www.omg.org/cgi-bin/doc?formal/01-09-67">UML&nbsp;1.4 
    standard</ulink> (versions of ArgoUML prior to 0.20 implemented the
    <ulink url="http://www.omg.org/cgi-bin/doc?formal/00-03-01">UML&nbsp;1.3 
    standard</ulink>). It is written in Java and runs on every computer 
    which provides a Java platform version 5 or newer. It uses the 
    open file formats 
    <indexterm><primary>XML</primary></indexterm>
    <ulink url="http://www.omg.org/cgi-bin/doc?formal/02-01-01">
    XMI</ulink> (XML Metadata Interchange format) (for model 
    information) and <ulink url="http://www.w3.org/TR/1998/NOTE-PGML">
    PGML</ulink> (Precision Graphics Markup Language) (for graph 
    information) for storage. When ArgoUML implements UML 2.0, PGML
    will be replaced by the UML Diagram Interchange specification.</para>

    <para>This manual is the cumulative work of several people and has 
    been evolving over several years. Connected to the release 0.10 of 
    ArgoUML, Jeremy Bennett, wrote a lot of the new material that was 
    added to the earlier versions by Alejandro Ramirez, Philippe 
    Vanpeperstraete and Andreas Rueckert. He also added things from 
    some of the other documents namely the developers cookbook by 
    Markus Klink and Linus Tolke, the Quick Guide by Kunle Odutola, and 
    the FAQ by Dennis Daniels. Connected to the release 0.14 changes 
    were made by Linus Tolke, and by Michiel van der Wulp. These 
    changes were mostly to adopt the manual to the new functions and 
    appearance of ArgoUML version 0.14, and introduction of the index. 
    The users and developers that have contributed by providing 
    valuable input, such as review comments or observations while 
    reading and using this manual are too many to name.</para>

    <para>ArgoUML is available for free and can be used in commercial 
    settings. For terms of use, see the license agreement presented 
    when you download ArgoUML. We are providing the source code for 
    ArgoUML for you to review, customize to your needs, and improve. 
    Over time, we hope that ArgoUML will evolve into a powerful and 
    useful tool for everyone to use.</para>

    <para>This User Manual is aimed at the working designer, who wishes 
    to make use of ArgoUML. The manual is presently written assuming 
    familiarity with UML, but eventually it will support those new to 
    UML.</para>

    <para>
      The manual is written in DocBook/XML and available as both 
      <indexterm><primary>XML</primary></indexterm>
      HTML and PDF.
    </para>

    <para>
    	The ArgoUML project welcomes those who want to get more
    	involved. Look at the
    	<ulink url="http://argouml.tigris.org/">project website</ulink>
    	to find out more.
    </para>

    <para>
    	Tell us what you think about this User Manual! Your comments
    	will help us improve things. See
    	<xref linkend="s2.intro.user.feedback" />
    	.
    </para>

  </preface>

  <chapter>

    <title>Introduction</title>

    <sect1>

      <title>Origins and Overview of ArgoUML</title>

      <sect2 id="s2.ooad">

        <title>Object Oriented Analysis and Design</title>

        <indexterm><primary>Analysis</primary></indexterm> 
        <indexterm><primary>Design</primary></indexterm>
        <para>Over the past decade, Object Oriented Analysis and Design 
        (OOA&amp;D) has become <emphasis>the</emphasis> dominant 
        software development paradigm. With it has come a major shift 
        in the thought processes of all involved in the software 
        development life cycle.</para>

        <para>Programming language support for objects began with 
        Simula&nbsp;67, but it was the emergence in the 1980&apos;s of 
        hybrid languages, such as C++, Ada and Object Pascal that 
        allowed OOA&amp;D to take off. These languages provided support 
        for both OO and procedural programming. Object Oriented 
        <emphasis>programming</emphasis> became mainstream.</para>

        <para>An OO system is designed and implemented as a 
        <emphasis>simulation</emphasis> of the real world using 
        software artifacts. This premise is as powerful as it is 
        simple. By using an OO approach to <emphasis>design</emphasis> 
        a system can be designed and tested (or more correctly 
        simulated) without having to actually build the system 
        first.</para>

        <para>It is the development during the 1990&apos;s of tools to 
        support Object Oriented <emphasis>analysis</emphasis> and 
        <emphasis>design</emphasis> that moved this approach into the 
        mainstream. When coupled with the ability to design systems at 
        a very high level, a tool based OOA&amp;D approach has enabled 
        the implementation of more complex systems than previously 
        possible.</para>

        <para>The final driver that has propelled OOA&amp;D has been 
        its suitability for modeling graphical user interfaces. The 
        popularity of object based and object oriented graphical 
        languages such as Visual Basic and Java reflect the 
        effectiveness of this approach.</para>

      </sect2>

      <sect2>

        <title>The Development of ArgoUML</title>

        <para>During the 1980&apos;s a number of OOA&amp;D process 
        methodologies and notations were developed by different 
        research teams. It became clear there were many common themes 
        and, during the 1990&apos;s, a unified approach for OOA&amp;D 
        notation was developed under the auspices of the 
        <ulink url="http://www.omg.org">Object Management 
        Group</ulink>. This standard became known as the Unified 
        Modeling Language (UML), and is now the standard language for 
        communicating OO concepts.</para>

        <para>ArgoUML was conceived as a tool and environment for use 
        in the analysis and design of object-oriented software systems. 
        In this sense it is similar to many of the commercial CASE 
        tools that are sold as tools for modeling software systems. 
        ArgoUML has a number of very important distinctions from many 
        of these tools.</para>

        <orderedlist>

          <listitem>

            <para>
              It is free.
            </para>

          </listitem>

          <listitem>

            <para>ArgoUML draws on research in cognitive psychology to 
            provide novel features that increase productivity by 
            supporting the cognitive needs of object-oriented software 
            designers and architects.</para>

          </listitem>

          <listitem>

            <para>ArgoUML supports open standards extensively - UML, XMI, 
            SVG, OCL and others.</para>

          </listitem>

          <listitem>

            <para>ArgoUML is a 100% pure Java application. This allows 
            ArgoUML to run on all platforms for which a reliable port 
            of the Java platform is available.</para>

          </listitem>

          <listitem>

            <para>ArgoUML is an open source project. The availability 
            of the source ensures that a new generation of software 
            designers and researchers now have a proven framework from 
            which they can drive the development and evolution of CASE 
            tool technologies.</para>

          </listitem>

        </orderedlist>

        <para>
        	UML is the most prevalent OO modeling language and Java is
        	one of the most productive OO development platforms. Jason
        	Robbins and the rest of his research team at the University
        	of California, Irvine leveraged these benefits in creating
        	ArgoUML. The result is a solid development tool and
        	environment for OO systems design. Further, it provides a
        	test bed for the evolution of object oriented CASE tools
        	development and research.
        </para>

        <para>A first release of ArgoUML was available in 1998 and more 
        than 100,000 downloads by mid-2001 show the impact that this 
        project has made, being popular in educational and commercial 
        fields.</para>

      </sect2>

      <sect2>

        <title>Finding Out More About the ArgoUML Project</title>

        <sect3>

          <title>How ArgoUML is Developed</title>

          <indexterm><primary>Jason Robbins</primary></indexterm>
          <indexterm><primary>Robbins, Jason</primary></indexterm>
          <indexterm><primary>Mailing lists</primary></indexterm>
          <para>Jason Elliot Robbins founded the Argo Project and 
          provided early project leadership. While Jason remains active 
          in the project, he has handed off project leadership. The 
          project continues to move forward strongly. There are more 
          than 300 members on the developer mailing list (see 
          <ulink url="http://argouml.tigris.org/servlets/ProjectMailingListList">
          http://argouml.tigris.org/servlets/ProjectMailingListList</ulink>), 
          with a couple of dozen of those forming the core development 
          group.</para>

          <para>
          	The developer mailing list is the place where all the
          	discussion on the latest tasks takes place, and developers
          	discuss the directions the project should take. Although
          	controversial at times, these discussions are always kept
          	nice and friendly (no flame-wars and such), so newbies
          	should not hesitate and participate in them. You&apos;ll
          	always get a warm welcome there.
          </para>

          <indexterm><primary>Contributing</primary><secondary>to 
          ArgoUML</secondary></indexterm>
          <indexterm><primary>Cookbook</primary></indexterm>
          <indexterm><primary>Developers&apos; Cookbook, 
          The</primary></indexterm>
          <indexterm><primary>Developer Zone</primary></indexterm>
          <para>
          	If you want to learn how the project is run and how to
          	contribute to it, go the the
          	<ulink url="http://argouml.tigris.org/dev.html">
          		ArgoUML Web Site Developer Zone
          	</ulink>
          	and read through the documentation there. The
          	Developers&apos; Cookbook was written specifically for
          	this purpose.
          </para>

        </sect3>

        <sect3>

          <title>More on Infrastructure</title>

          <indexterm><primary>Mailing lists</primary></indexterm>
          <para>
          	Besides the developer mailing list, there&apos;s also a
          	mailing for users (see
          	<ulink
          		url="http://argouml.tigris.org/servlets/ProjectMailingListList">
          		The ArgoUML Mailing List List
          	</ulink>
          	), where we can discuss problems from a user perspective.
          	Developers also read this list, so highly qualified help
          	will generally be provided.
          </para>

          <indexterm><primary>FAQ</primary></indexterm>
          <para>Before posting to this list, you should take a look at 
          the <ulink url="http://argouml.tigris.org/faqs/users.html">
          user FAQ</ulink> maintained by Ewan R. Grantham.</para>

          <para>More information on ArgoUML and other UML related 
          topics is also available on the 
          <ulink url="http://argouml.tigris.org">ArgoUML 
          website</ulink>, maintained by Linus Tolke.</para>

        </sect3>

      </sect2>

    </sect1>

    <sect1>

      <title>Scope of This User Manual</title>

      <sect2>

        <title>Target Audience</title>

        <para>The current release of this document is aimed at 
        experienced users of UML in OOA&amp;D (perhaps with other 
        tools) who wish to transfer to ArgoUML.</para>

        <para>Future releases will support designers who know 
        OOA&amp;D, and wish to adopt UML notation within their 
        development process.</para>

        <para>A long term goal is to support i) those who are learning 
        design and wish to start with an OOA&amp;D process that uses 
        UML notation, and ii) people interested in modularized code 
        design with a GUI.</para>

      </sect2>

      <sect2>

        <title>Scope</title>

        <para>The intention is that this document will provide a 
        comprehensive guide, enabling designers to use ArgoUML to its 
        full extent. It is in two parts.</para>

        <itemizedlist>

          <listitem>

            <para>A tutorial manual, showing how to work with 
            ArgoUML</para>

          </listitem>

          <listitem>

            <para>A complete reference manual, recording everything you 
            can do with ArgoUML.</para>

          </listitem>

        </itemizedlist>

        <para>
        	Version 0.22 of the document achieved the second of these.
        </para>

        <para>In this guide there are some things you will not find, 
        because they are covered elsewhere.</para>

        <itemizedlist>

          <listitem>

            <para>Descriptions of how ArgoUML works on the 
            inside.</para>

          </listitem>

          <listitem>

            <para>How to improve ArgoUML with new features and 
            functions.</para>

          </listitem>

          <listitem>

            <para>A trouble shooting guide.</para>

          </listitem>

          <listitem>

            <para>A summary quick reference to using ArgoUML.</para>

          </listitem>

        </itemizedlist>

        <para>These are covered in 
        <ulink url="http://argouml-stats.tigris.org/documentation/defaulthtml/cookbook/">
        the Developers Cookbook</ulink>, 
        <ulink url="http://argouml.tigris.org/faqs/users.html">the 
        FAQ</ulink>, and 
        <ulink url="http://argouml-stats.tigris.org/documentation/quick-guide-0.26/">
        the Quick Guide</ulink>.</para>

      </sect2>

    </sect1>

    <sect1>

      <title>Overview of the User Manual</title>

      <sect2>

        <title>Tutorial Manual Structure</title>

        <para><xref linkend="ch.tut.uml"/> provides an overview of UML 
        based OOA&amp;D, including a guide to getting ArgoUML up and 
        running.</para>

        <para><xref linkend="ch.tut.reqs"/> through 
        <xref linkend="ch.tut.build"/> then step through each part of 
        the design process from initial requirements capture through to 
        final project build and deployment.</para>

        <para>As each UML concept is encountered, its use is explained. 
        Its use within ArgoUML is then described.
        Finally a case study is used to give examples of the concepts in use.</para>

      </sect2>

      <sect2>

        <title>Reference Manual Structure</title>

        <para><xref linkend="ch.ref.ui"/> is an overview of the user 
        interface and provides a summary of the support for the various 
        UML diagram types in ArgoUML.
        <xref linkend="ch.ref.menu"/> and <xref linkend="ch.ref.navpane"/>  
        describe the menu bar, and each of the sub-windows of the user interface, known as <emphasis>Panes</emphasis>.</para>

        <para><xref linkend="ch.ref.critics"/> gives details of all the 
        cognitive critics within the system. Eventually ArgoUML will 
        link directly to this manual when giving advice on 
        critics.</para>

        <para><xref linkend="ch.ref.entities"/> is an overview of the 
        model elements (i.e. the UML entities that can be placed on 
        diagrams) within ArgoUML. The following chapters (
        <xref linkend="ch.ref.entusecase"/> through 
        <xref linkend="ch.ref.entbuiltin"/>) describe, the model elements 
        that can be created through each ArgoUML diagram, and their 
        properties, as well as some standard model elements provided with 
        the system.</para>

        <para>A complete <xref linkend="glossary"/> is provided. 
        <xref linkend="app.casestudy"/> provides material to supplement 
        the case study used throughout the document. 
        <xref linkend="app.umlres"/> and <xref linkend="app.umlcase"/> 
        identify background information on UML and UML CASE tools. 
        <xref linkend="app.cppmod"/> explains the use of the C++ module.
        <xref linkend="app.legal"/> is a copy of the GNU Free 
        Documentation License.</para>

      </sect2>

      <sect2 id="s2.intro.user.feedback">

        <title>User Feedback</title>

        <indexterm><primary>Feedback</primary></indexterm>
        <indexterm><primary>User Feedback</primary></indexterm>
        <indexterm><primary>Contributing</primary><secondary>to the 
        User Manual</secondary></indexterm>
        <para>Please tell us what you think about this User Manual. 
        Your comments will help us make improvements.
        Email your 
        thoughts to the <ulink url="mailto:users@argouml.tigris.org">
        ArgoUML Users Mailing List</ulink>.
        In case you would like to add to the missing chapters you should contact the 
        <ulink url="mailto:dev@argouml.tigris.org">ArgoUML Developer Mailing List</ulink>
        to check whether anyone else is working on this part.
        You can subscribe to either of the mailing lists via the
        <ulink url="http://argouml.tigris.org">ArgoUML web site</ulink>.</para>

      </sect2>

    </sect1>

    <sect1>

      <title>Assumptions</title>

      <para>This release of the manual assumes the reader is very 
      familiar with UML already. This is reflected in the sparseness of 
      the description of UML concepts in the tutorial.</para>

      <para>The case study is described, but not yet fully realized 
      throughout the tutorial. This will be achieved in future releases 
      of the manual.</para>

    </sect1>

  </chapter>

  <part>

    <title>Tutorial</title>

    <chapter id="ch.tut.uml">

      <title>Introduction (being written)</title>

      <para>
        This tutorial will be taking you through a tour of the use of
        ArgoUML to model a system.
      </para>

      <para>
        First you will become familiar with the feel of the product and then
        we will go through an analysis and development process for a test case.
        Not every nook and cranny of the product will be demonstrated.
        That degree of detail is given in the reference materials to be
        found in subsequent parts of this document.
      </para>

      <para>
        The state of the model at the end of key sections will be available in
        .zargo files.
        These are available so that you can play with various aspects not
        specifically covered in this tutorial and then
        restore yourself back to the proper state of the model in your work area.
        These .zargo files will be identified at the end of the sections whose
        work they represent.
      </para>

      <para>
        An ATM (automated teller machine) project has been chosen as a case study
        to demonstrate the various aspects of modeling that ArgoUML offers.
        In subsequent sections we are going to develop the ATM example into
        a complete description in UML.
        The tutorial, however, will only walk you through part of it.
      </para>

      <para>
        At this point you should create a directory to contain your project.
        Name the directory anything you feel is consistent with the rest of your
        file system.
        You should name the contents and any subdirectories as directed for reasons
        that will become apparent.
      </para>

      <para>
        The case study will be an ATM system.
        Your company is FlyByNight Industries.
        You are going to play two roles.
        That of the Project Manager and that of the Designer Analyst.
      </para>

      <para>
        We are not going to build a physical ATM, of course.
        The product that we will build as a case study will be an ATM simulator
        to be used for testing the design of a physical ATM.
      </para>

      <para>
        How your company arranges its work into projects is usually determined as
        much by politics as anything else and is, therefore, out of the scope of
        this document.
        We will go into how you structure the project itself once one has been
        defined.
      </para>

    </chapter>

    <chapter id="ch.tut.ooad">

      <title>UML Based OOA&amp;D</title>

      <para>
        In this chapter, we look at how UML as a notation is used 
        within OOA&amp;D.
      </para>

      <sect1>

        <title>Background to UML</title>

        <para><emphasis>Object orientation</emphasis> as a concept has 
        been around since the 1960&apos;s, and as a design concept 
        since 1972. However it was in the 1980&apos;s that it started 
        to develop as a credible alternative to a <emphasis>functional 
        approach</emphasis> in analysis and design. We can identify a 
        number of drivers.</para>

        <orderedlist>

          <listitem>

            <para>The emergence of mainstream OO programming languages 
            like SmallTalk and particularly C++. C++ was a pragmatic OO 
            language derived from C, widely used because of its 
            association with Unix.</para>

          </listitem>

          <listitem>

            <para>The development of powerful workstations, and with 
            them the emergence into the mainstream of windowing 
            operating user environments. Graphical User Interfaces 
            (GUI) have an inherent object structure.</para>

          </listitem>

          <listitem>

            <para>A number of very public major project failures, 
            suggesting that current approaches were not 
            satisfactory.</para>

          </listitem>

        </orderedlist>

        <para>A number of researchers proposed OOA&amp;D processes, and 
        with them notations. Those that achieved some success include 
        Coad-Yourdon, Booch, Rumbaugh OMT, OOSE/Jacobson, 
        Shlaer-Mellor, ROOM (for real-time design) and the hybrid 
        Jackson Structured Development.</para>

        <para>During the early 1990&apos;s it became clear that these 
        approaches had many good ideas, often very similar. A major 
        stumbling block was the diversity of notation, meaning 
        engineers tended to be familiar with one OOA&amp;D methodology, 
        rather than the approach in general.</para>

        <para>UML was conceived as a common notation, that would be in 
        the interests of all involved. The original standard was driven 
        by Rational Software (
        <ulink url="http://www.rational.com">www.rational.com</ulink>, 
        in which three of the key researchers in the field (Booch, 
        Jacobson and Rumbaugh were involved). They produced documents 
        describing UML v0.9 and v0.91 during 1996. The effort was taken 
        industry wide through the Object Management Group (OMG), 
        already well known for the CORBA standard. A first proposal, 
        1.0 was published in early 1997, with an improved version 1.1 
        approved that autumn.</para>

        <para>ArgoUML is based on UML v1.4, which was adopted by OMG in 
        September 2001. The current official version, supported by ArgoUML, 
         is UML v1.4.2 dated July 2004, adopted as ISO/IEC 19501.
        The latest UML version is UML v2.1.2, from November 2007.
        </para>

      </sect1>

      <sect1>

        <title>UML Based Processes for OOA&amp;D</title>

        <para>
          It is important to understand that UML is a notation for OOA&amp;D.
          It does not prescribe any particular process.
          Whatever process is adopted, it must take the system 
          being constructed through a number of phases.
        </para>

        <orderedlist>

          <listitem>

            <para>Requirements Capture. This is where we identify the 
            requirements for the system, using the language of the 
            <emphasis>problem domain</emphasis>. In other words we 
            describe the problem in the <quote>customer&apos;s</quote> 
            terms.</para>

          </listitem>

          <listitem>
            <indexterm><primary>Analysis</primary></indexterm> 

            <para>Analysis. We take the requirements and start to 
            recast them in the language of a putative solution&mdash;the 
            <emphasis>solution domain</emphasis>. At this stage, 
            although thinking in terms of a solution, we ensure we keep 
            things at a high level, away from concrete details of a 
            specific solution&mdash;what is known as 
            <emphasis>abstraction</emphasis>.</para>

          </listitem>

          <listitem>
            <indexterm><primary>Design</primary></indexterm>

            <para>Design. We take the specification from the Analysis 
            phase and construct the solution in full detail. We are 
            moving from <emphasis>abstraction</emphasis> of the problem 
            to its <emphasis>realization</emphasis> in concrete 
            terms.</para>

          </listitem>

          <listitem>

            <para>Build Phase. We take the actual design and write it 
            in a real programming language. This includes not just the 
            programming, but the testing that the program meets the 
            requirements (<emphasis>verification</emphasis>), testing 
            that the program actually solves the customer&apos;s 
            problem (<emphasis>validation</emphasis>) and writing all 
            user documentation.</para>

          </listitem>

        </orderedlist>

        <sect2 id="s2.proctypes">

          <title>Types of Process</title>

          <para>In this section we look at the two main types of 
          process in use for software engineering. There are others, 
          but they are less widely used.</para>

          <para>In recent years there has also been a move to reduce 
          the effort required in developing software. This has led to 
          the development of a number of lightweight variants of 
          processes (often known as <emphasis>agile 
          computing</emphasis> or <emphasis>extreme 
          programming</emphasis>) that are suited to small teams 
          of engineers.</para>

          <sect3>

            <title>The Waterfall Process</title>

            <para>In this process, each stage of the 
            process&mdash;requirements, analysis, design and build (code and 
            test) is completed before the next one starts. This is 
            illustrated in <xref linkend="fig.waterfallsteps"/>.</para>

            <figure float="1" id="fig.waterfallsteps">

              <title>The Waterfall Process</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/waterfallsteps.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>This is a very satisfactory process where 
            requirements are well designed and not expected to change, 
            for example automating a well proven manual system.</para>

            <para>The weaknesses of this approach show with less well 
            defined problems. Invariably some of the uncertainties in 
            the requirements will not be clarified until well into the 
            analysis and design, or even code phases, requiring 
            backtracking to redo work.</para>

            <para>The worst aspect of this, is that working code does 
            not become available until near the end of the project, and 
            very often it is only at this stage that problems with the 
            original requirements (for example with the user interface) 
            become apparent.</para>

            <para>This is exacerbated, by each successive stage 
            requiring more effort, than the previous, so that the costs 
            of late problem discovery are hugely expensive. This is 
            illustrated by the pyramid in 
            <xref linkend="fig.waterfall"/>.</para>

            <figure float="1" id="fig.waterfall">

              <title>Effort Involved in the Steps of the Waterfall 
              Process</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/waterfall.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>The waterfall process is still probably the dominant 
            design process. However because of its limitations it is 
            increasingly replaced by <emphasis>iterative</emphasis> 
            processes, particularly for projects where the requirements 
            are not well defined.</para>

          </sect3>

          <sect3>

            <title>Iterative Development Processes</title>
            <indexterm><primary>Iterative Processes</primary></indexterm>

            <para>In recent years a new approach has been used, which 
            aims to get at least part of the code up and running as 
            quickly as possible, to bring discovery of problems forward 
            in the development cycle.</para>

            <para>These processes use a series of 
            <quote>mini-waterfalls</quote>, defining a few requirements 
            (the most important) first, taking them through analysis, 
            design and build to get an early version of the product, 
            with limited functionality, related to the most important 
            requirements. Feedback from this can then be used to refine 
            the requirements, spot problems etc before more work is 
            done.</para>

            <para>The process is then repeated for further requirements 
            to construct a product with a step up in functionality. 
            Again further feedback can be applied to the 
            requirements.</para>

            <para>
              The process is repeated, until eventually all 
              requirements have been implemented and the product is 
              complete.
              <indexterm><primary>Iteration</primary></indexterm>
              It is this <emphasis>iteration</emphasis> that 
              gives these processes their name. 
              <xref linkend="fig.iterative"/> shows how this process 
              compares to the pyramid structure of the Waterfall 
              Process.
            </para>

            <figure float="1" id="fig.iterative">

              <title>Effort Involved in the Steps of an Iterative 
              Process</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/iterative.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>The growth in popularity of iterative processes is 
            closely tied to the growth of OOA&amp;D. It is the clean 
            encapsulation of objects that allows a part of a system to 
            be built with stubs for the remaining code clearly 
            defined.</para>

            <sect4>

              <title>The Rational Unified Process</title>

              <para>Perhaps the best known Iterative Process is the 
              Rational Unified Process (RUP) from Rational Software (
              <ulink url="http://www.rational.com">www.rational.com</ulink>).</para>

              <para>This process recognizes that our pyramid view of 
              even slices of the waterfall is not realistic. In 
              practice the early iterations tend to be heavy on the 
              requirements end of things (you need to define a 
              reasonable amount even to get started), while the later 
              iterations have more of their effort in the design and 
              build areas.</para>

              <para>RUP recognizes that iterations can be grouped into 
              a number of <emphasis>phases</emphasis> according to 
              their stage in the overall project. Each phase may have 
              one or more iterations.</para>

              <itemizedlist>

                <listitem>

                  <para>In the <emphasis>inception phase</emphasis> 
                  iterations tend to be heavy on the 
                  requirements/analysis end, while any build activity 
                  may be limited to emulation of the design within a 
                  CASE tool.</para>

                </listitem>

                <listitem>

                  <para>In the <emphasis>elaboration phase</emphasis> 
                  iterations tend to be completing the specification of 
                  the requirements, and starting to focus on the 
                  analysis and design, and possibly the first real 
                  built code.</para>

                </listitem>

                <listitem>

                  <para>In the <emphasis>construction phase</emphasis> 
                  iterations the requirements and analysis are more or
                  less completed, and the effort is mostly in design
                  and build.</para>

                </listitem>

                <listitem>

                  <para>Finally, in the <emphasis>deployment 
                  phase</emphasis> iterations are largely about build 
                  activity, and in particular the testing of the 
                  software.</para>

                </listitem>

              </itemizedlist>

              <note>

                <para>It should be clear that testing is an integral 
                part of all phases. Even in the early phases the 
                requirements and design should be tested, and this is 
                facilitated by a good CASE tool.</para>

              </note>

              <para>We shall use an iterative process in this manual, 
              that is loosely based on the RUP.</para>

            </sect4>

            <sect4>

              <title>Iteration Size</title>

              <para>
                A good rule of thumb is that an iteration should take
                between six and ten weeks for typical commercial projects.
                Any longer and you have probably bitten off too many
                requirements to do in one go. You also lose focus on
                getting the next working iteration completed.
                Any shorter and you probably haven&apos;t got enough
                requirements to make a significant advance.
                In this case the additional overhead associated with an
                interation will become a problem.
              </para>

              <para>
                The total number of iterations depends on the size of project.
                Take the estimated time (working out/guessing that is a
                whole subject on its own), and divide it into 8 week chunks. 
                Experience seems to suggest that the iterations will 
                divide in the ratio of around 1:2:3:3 into RUP style 
                inception, elaboration, construction and deployment 
                phases. A project that has great vagueness in its 
                specification (some advanced research projects for 
                example) will tend to be heavier on the early 
                phases.
              </para>

              <para>When building a product to contract for a customer 
              the end point is well defined. However when developing a 
              new product for the market place, a strategy that can be 
              used is to decide the product launch date, and hence the 
              end date for completion of engineering (some time 
              before). The time is then divided into iterations, and as 
              much of the product as can be built in that time 
              developed. The iterative process is very effective where 
              time to market is more important than the exact 
              functionality.</para>

            </sect4>

          </sect3>

          <sect3>

            <title>Recursive Development Processes</title>

            <para>Very few software systems are conceived as monolithic 
            artifacts. They are broken down into subsystems, modules 
            etc.</para>

            <para>Software processes are the same, with early parts of 
            the process defining a top level structure, and the process 
            reapplying to parts of the structure in turn to define ever 
            greater details.</para>

            <para>For example the initial design of a telephone system 
            might identify objects to i) handle the phone lines, ii) 
            process the calls, iii) manage the system and iv) bill the 
            customer. The software process can then be reapplied to 
            each of these four components to identify their 
            design.</para>

            <para>OOA&amp;D with its clean boundaries to objects, 
            naturally supports this approach. Such OOA&amp;D with 
            recursive development is sometimes abbreviated as 
            OOA&amp;D/RD.</para>

            <para>Recursive development can be applied equally well to 
            waterfall or iterative processes. It is not an alternative 
            to them.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>A Development Process for This Tutorial</title>

          <para>For the purpose of this tutorial we will use a stripped 
          down iterative process with recursive development, loosely 
          akin to RUP. The case study will take us through the first 
          iteration, although at the end of the tutorial section of the 
          manual we will look at how the project will develop to 
          completion.</para>

          <para>Within that first iteration, we will tackle each of the 
          requirements capture, analysis, design and build activities 
          in turn. Not all parts of the process are based on UML or 
          ArgoUML. We will look at what other material is needed 
          outside.</para>

          <para>Within this process we will have an opportunity to see 
          the various UML diagrams in use. The full range of UML 
          diagrams and how they are supported is described in the 
          reference manual (see <xref linkend="s1.ref.diagram_types"/>
          ).</para>

          <sect3>

            <title>Requirements Capture</title>

            <para>Our requirements capture will use the UML concept of 
            <emphasis>Use Cases</emphasis>. Starting with a 
            <emphasis>Vision Document</emphasis> we will see how Use 
            Cases can be developed to describe all aspects of the 
            system&apos;s behavior in the problem domain.</para>

          </sect3>

          <sect3>

            <title>Analysis</title>

            <indexterm><primary>Analysis</primary></indexterm> 
            <para>During the analysis stage, we will introduce the UML 
            concept of <emphasis>classes</emphasis> to allow us to 
            build a top level view of the objects that will make up the 
            solution&mdash;sometimes known as a <emphasis>concept 
            diagram</emphasis>.</para>

            <para>We will introduce the UML <emphasis>sequence 
            diagram</emphasis> and <emphasis>statechart 
            diagram</emphasis> to capture requirements for the overall 
            behavior of the system.</para>

            <para>Finally we will take the Use Cases from the 
            requirements capture stage, and recast them in the language 
            of the solution domain. This will illustrate the UML ideas 
            of <emphasis>stereotyping</emphasis> and 
            <emphasis>realization</emphasis>.</para>

          </sect3>

          <sect3>

            <title>Design</title>

            <indexterm><primary>Design</primary></indexterm>
            <para>We use the UML <emphasis>package diagram</emphasis> 
            to organize the components of the project. We then revisit 
            the class diagram, sequence diagram and statechart diagram, 
            to show how they can be used recursively to design the 
            complete solution.</para>

            <para>During this part of the process, we need to develop 
            our system architecture, to define how all the components 
            will fit together and operate.</para>

            <para>Although not strictly part of our process, we&apos;ll 
            look at how the UML <emphasis>collaboration 
            diagram</emphasis> can be used as an alternative to, or to 
            complement the <emphasis>sequence diagram</emphasis>. 
            Similarly we will look at the UML <emphasis>activity 
            diagram</emphasis> as an alternative or complement to the 
            statechart diagram.</para>

            <para>Finally we shall use the UML <emphasis>deployment 
            diagram</emphasis> to specify how the system will actually 
            be realized.</para>

          </sect3>

          <sect3>

            <title>Build</title>

            <indexterm><primary>Build</primary></indexterm>
            <para>UML is not really concerned with code writing. 
            However at this stage we will show how ArgoUML can be used 
            for code generation.</para>

            <para>We will also look at how the UML Use Case Diagram and 
            Use Case Specification are invaluable tools for a test 
            program.</para>

          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Why ArgoUML is Different</title>

        <para>In the introduction, we listed the four key things that 
        make ArgoUML different: i) it makes use of ideas from cognitive 
        psychology, ii) it is based on open standards; iii) it is 100% 
        pure Java; and iv) it is an open source project.</para>

        <sect2 id="tut.cog.psych">

          <title>Cognitive Psychology</title>

          <sect3>

            <title>Theory</title>

            <para>ArgoUML is particularly inspired by three theories 
            within cognitive psychology: i) reflection-in-action, ii) 
            opportunistic design iii) and comprehension and problem 
            solving.</para>

            <itemizedlist>

              <listitem><para><emphasis>Reflection-in-Action</emphasis>
                <indexterm><primary>Reflection-in-Action</primary></indexterm>
                </para>
                
                <para>
                  This theory observes that designers of complex systems do not
                  conceive a design fully-formed. Instead, 
                  they must construct a partial design, evaluate, reflect 
                  on, and revise it, until they are ready to extend it further.
                </para>

                <para>
                  As developers work hands-on with the design, their mental model
                  of the problem situation improves, hence improving their design.
                </para>
              </listitem>

              <listitem><para><emphasis>Opportunistic Design</emphasis>
                <indexterm><primary>Opportunistic Design</primary></indexterm>
                </para>

                <para>
                  A theory within cognitive psychology suggesting that although
                  designers plan and describe their work in an ordered, hierarchical
                  fashion, in reality, they choose successive tasks based on the
                  criteria of cognitive cost.
                </para>

                <para>
                  Simply stated, designers do not follow even their own plans in
                  order, but choose steps that are mentally least expensive among
                  alternatives.
                </para>
              </listitem>

              <listitem><para><emphasis>Comprehension and Problem Solving</emphasis>
                <indexterm><primary>Comprehension</primary></indexterm>
                <indexterm><primary>Problem Solving</primary></indexterm>
                </para>

                <para>
                  A design visualization theory within cognitive psychology.
                  The theory notes that designers must bridge a gap between their
                  mental model of the problem or situation and the formal model of
                  a solution or system.
                </para>

                <para>
                  This theory suggests that programmers will benefit from:
                </para>

                <orderedlist>

                  <listitem>

                    <para>
                      Multiple representations such as program syntactic
                      decomposition, state transitions, control flow, and data flow.
                      These allow the programmer to better identify elements and
                      relationships in the problem and solution and thus more
                      readily create a mapping between their situation models and
                      working system models.
                    </para>

                  </listitem>

                  <listitem>

                    <para>
                      Familiar aspects of a situation model, which improve
                      designers&apos; abilities to formulate solutions.
                    </para>

                  </listitem>

                </orderedlist>

              </listitem>
            </itemizedlist>

          </sect3>

          <sect3>

            <title>Practical Application in ArgoUML</title>

            <para>
              ArgoUML implements these theories using a number of techniques.
            </para>


            <orderedlist>

              <listitem>

                <para>The design of a user interface which allows the 
                user to view the design from a number of different 
                perspectives, and allows the user to achieve goals 
                through a number of alternative routes.</para>

              </listitem>

              <listitem>

                <para>The the use of processes running in parallel with 
                the design tool, evaluating the current design against 
                models of how <quote>best practice</quote> design might 
                work. These processes are known as <emphasis>design 
                critics</emphasis>.</para>

              </listitem>

              <listitem>

                <para>The use of <emphasis>to-do lists</emphasis> to 
                convey suggestions from the design critics to the user, 
                as well as allowing the user to record areas for future 
                action.</para>

              </listitem>

              <listitem>

                <para>The use of checklists, to guide the user through 
                a complex process.</para>

              </listitem>

            </orderedlist>

          </sect3>

        </sect2>

        <sect2>

          <title>Open Standards</title>

          <para>UML is itself an open standard. ArgoUML throughout has 
          tried to use open standards for all its interfaces.</para>

          <para>
            The key advantage of adherence to open standards is that it
            permits easy inter-working between applications, and the ability
            to move from one application to another as necessary.
          </para>

          <sect3>

            <title>XML Metadata Interchange (XMI)</title>

            <indexterm><primary>XMI</primary></indexterm>
            <para><emphasis>XML Metadata Interchange (XMI)</emphasis> 
            is the standard for saving the meta-data that make up a 
            particular UML model. In principle this will allow you to 
            take the model you have created in ArgoUML and import it 
            into another tool.</para>

            <para>This clearly has advantages in allowing UML to meet 
            its goal of being a standard for communication between 
            designers.</para>

            <para>
              The reality is not quite this good.
              Prior to UML 2.0 the XMI file includes no information about the
              graphical representation of the models, so diagram layout is lost.
              ArgoUML gets round this by saving graphical information separate
              from the model
              (see <xref linkend="s3.tut.loadsave"/>).
            </para>

          </sect3>

          <sect3>

            <title>Graphics Formats - EPS, GIF, PGML, PNG, PS, SVG</title>

            <itemizedlist>

              <listitem><para>
                <indexterm><primary>EPS</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/Encapsulated_PostScript"><emphasis>Encapsulated
                PostScript (EPS)</emphasis></ulink> file is a
                PostScript file which satisfies additional restrictions.
                These restrictions are intended to make it easier for software
                to embed an EPS file within another PostScript document.
              </para></listitem>

              <listitem><para>
                <indexterm><primary>GIF</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/GIF"><emphasis>Graphics
                Interchange Format (GIF)</emphasis></ulink> uses lossless compression, 
                and preserves sharp edges well, which makes it well-suited for ArgoUML.
                The GIF format used to be a patent encumbered format, 
                but all the patents have currently expired.
              </para></listitem>

              <listitem><para>
                <indexterm><primary>PGML</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/PGML">
                <emphasis>Precision Graphics Markup Language (PGML)</emphasis></ulink>
                is an XML-based
                language for representing vector graphics.
                It was a W3C draft, but was not adopted as a recommendation.
                PGML and VML, another XML-based vector graphics language, were
                later joined and improved upon to create SVG (see below).
              </para></listitem>
                
              <listitem><para>
                <indexterm><primary>PNG</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/Portable_Network_Graphics">
                <emphasis>Portable Network Graphics (PNG)</emphasis></ulink> is an
                ISO/IEC standard (15948:2004) and is also a W3C recommendation.
                PNG is a bitmap image format that employs lossless data
                compression. PNG was created to both improve upon and replace
                the GIF format with an image file format that does not require
                a patent license to use.
                PNG is officially pronounced "ping" but it is often just
                spelled out &mdash; probably to avoid confusion with the
                network tool ping.
                PNG is supported by the libpng reference library,
                a platform-independent library that contains C functions for
                handling PNG images.
              </para></listitem>

              <listitem><para>
                <indexterm><primary>PS</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/PostScript">
                  <emphasis>PostScript (PS)</emphasis>
                </ulink> is a page description language and
                programming language used primarily in the electronic and
                desktop publishing areas.
              </para></listitem>

              <listitem><para>
                <indexterm><primary>SVG</primary></indexterm>
                <ulink url="http://en.wikipedia.org/wiki/Scalable_Vector_Graphics">
                <emphasis>Scalable Vector Graphics (SVG)</emphasis></ulink>
                is an XML markup language for describing two-dimensional
                vector graphics, both static and animated, and either declarative
                or scripted.
                It is an open standard created by the World Wide Web Consortium.
                <!-- The next part is too literally copied from wikipedia: -->
                The use of SVG on the web is in its infancy.
                There is a great deal of inertia due to the long-time use of pure
                raster formats and other formats like Macromedia Flash or Java
                applets, but also browser support is still uneven, with native
                support in Opera, Safari and Firefox, but Internet Explorer
                requires a plugin.
                See PGML above.
              </para></listitem>

            </itemizedlist>

          </sect3>

          <sect3>

            <title>Object Constraint Language (OCL)</title>
            <para>
              <ulink url="http://en.wikipedia.org/wiki/Object_Constraint_Language">
              <emphasis>Object Constraint Language (OCL)</emphasis></ulink>
              is a declarative language for describing rules that apply
              to UML models.
              It was developed at IBM and is now part of the UML standard.
              Initially OCL was only a formal specification language
              extension to UML.
              OCL may now be used with any Meta-Object Facility (MOF) compliant
              metamodel, including UML.
              The Object Constraint Language is a precise text language
              that provides constraint and object query expressions on any
              MOF model or metamodel that cannot otherwise be expressed by
              diagrammatic notation.
            </para>

          </sect3>

        </sect2>

        <sect2>

          <title>100% Pure Java</title>

          <para>Java was conceived as an interpreted language. It 
          doesn&apos;t have a compiler to produce code for any 
          particular target machine. It compiles code for its own 
          target, the <emphasis>Java Virtual Machine 
          (JVM)</emphasis>.</para>

          <para>Writing an interpreter for a JVM is much easier than 
          writing a compiler, and such machines are now incorporated 
          into almost every Web Browser. As a result most machines can 
          run Java, with no further work.</para>

          <para>(In case you wonder why all languages aren&apos;t like 
          this, it is because interpreted languages tend to be slower 
          than compiled languages. However with the high performance of 
          modern PCs, the trade-off for portability is worthwhile for 
          many applications. Furthermore modern multi-level caches can 
          mean that interpreted languages, which produce denser code, 
          may actually not be that much slower anyway.)</para>

          <para>By choosing to write ArgoUML in pure Java, it is 
          immediately made available to the maximum number of users 
          with the minimum amount of effort.</para>

        </sect2>

        <sect2>

          <title>Open Source</title>

          <para>ArgoUML is an <emphasis>open source</emphasis> project. 
          That means anyone can have a free copy of the source code, 
          change it, use it for new purposes and so on. The only 
          (major) obligation is that you pass your code on in the same 
          way to others. The precise nature of what you can and 
          can&apos;t do varies from project to project, but the 
          principle is the same.</para>

          <para>
            The advantage is that a small project like ArgoUML 
            suddenly is open to a lot of additional help from those who 
            can chip in their ideas for how the program might be 
            improved.
            At any one time there may be 10, 15, 20 or more 
            people making significant contributions to ArgoUML.
            To do that commercially would cost $1m+ per year.
          </para>

          <para>Its not just a spirit of pure altruism. Contributing is 
          a way of learning <quote>hands-on</quote> about leading edge 
          software. Its a way of getting a lot of visibility (over 
          1,125,000 people had downloaded ArgoUML by the end of 2005). 
          That&apos;s a lot of good experience on a r&eacute;sum&eacute;
          and a lot of 
          potential employers seeing you!</para>

          <para>And its great for the ego!</para>

          <para>Open Source doesn&apos;t preclude making money. 
          Gentleware <ulink url="http://www.gentleware.com">
          www.gentleware.com</ulink> sell a commercial version of 
          ArgoUML, Poseidon. Their value proposition is not a piece of 
          private code. Its the commercial polish and support that take 
          risk out of using ArgoUML in a commercial development, 
          allowing customers to take advantage of ArgoUML&apos;s 
          leading edge technology.</para>

        </sect2>

      </sect1>

      <sect1 id="tut.basics">

        <title>ArgoUML Basics</title>

        <para>The aim of this section is to get you started with 
        ArgoUML. It takes you through obtaining the code and getting it 
        running.</para>

        <sect2>

          <title>Getting Started</title>

          <sect3 id="s3.tut.system.requirements">

            <title>System Requirements</title>

            <para>Since ArgoUML is written in 100% pure Java, it should 
            run on any machine with Java installed. Java version 5
            or later is needed. You may have this in place, but if not 
            the latest version can be downloaded free from 
            <ulink url="http://www.java.com">www.java.com</ulink>. Note 
            that you only need the Java Runtime Environment (JRE), 
            there is no need to download the whole Java Development Kit 
            (JDK).</para>

            <para>ArgoUML needs a reasonable amount of computing 
            resource. 
            Any PC which is able to run an operating system with 
            a graphical user interface will suffice. 
            Download 
            the code from Download section of the project website 
            <ulink url="http://argouml.tigris.org">
            argouml.tigris.org</ulink>. Choose the version that suits 
            your needs as described in the section below.</para>

          </sect3>

          <sect3>

            <title>Downloading Options</title>

            <para>You have three options for obtaining ArgoUML.</para>

            <orderedlist>

              <listitem>

                <para>Run ArgoUML directly from the Web Site using Java 
                Web Start. This is the easiest option.</para>

              </listitem>

              <listitem>

                <para>Download the Windows installer program. This is the 
                right option if you are on Windows 
                and intend using ArgoUML regularly.</para>

              </listitem>

              <listitem>

                <para>Download the binary executable code. 
                Unless you are on Windows, this is the 
                right option if you intend using ArgoUML regularly and 
                is not that difficult.</para>

              </listitem>

              <listitem>

                <para>
                  <indexterm><primary>Build</primary></indexterm>
                  Download the source code using Subversion and build your own version.
                  Choose this option if you want to look at the internal
                  workings of ArgoUML, or want to join in as a developer.
                  This option does require the whole JDK 
                  (see <xref linkend="s3.tut.system.requirements"/>).
                </para>

              </listitem>

            </orderedlist>

            <para>All four options are freely available through the 
            project web site, <ulink url="http://argouml.tigris.org">
            argouml.tigris.org</ulink>.</para>

          </sect3>

          <sect3>

            <title>ArgoUML Using Java Web Start</title>

            <para>There are two steps to this.</para>

            <orderedlist>

              <listitem>

                <para>Install Java Web Start on your machine. This is 
                available from 
                <ulink url="http://java.sun.com/products/javawebstart">
                java.sun.com/products/javawebstart</ulink>, or via the 
                <literal>Java Web Start</literal> link on the ArgoUML 
                <ulink url="http://argouml.tigris.org">home 
                page</ulink>.</para>

              </listitem>

              <listitem>

                <para>Click on the <literal>Launch latest stable 
                release</literal> link on the ArgoUML 
                <ulink url="http://argouml.tigris.org">home 
                page</ulink>.</para>

              </listitem>

            </orderedlist>

            <para>Java Web Start will download ArgoUML, cache it and 
            start it the first time, then on subsequent starts, check 
            if ArgoUML is updated and only download any updated parts 
            and then start it. The ArgoUML 
            <ulink url="http://argouml.tigris.org">home page</ulink> 
            also provides details on starting ArgoUML from the Java Web 
            Start console.</para>

          </sect3>

          <sect3>

            <title>Using the Windows installer</title>

            <para>If you choose to download and install 
            using the Windows installer, you 
            will have a choice of downloading the latest stable version 
            of the code (which will be more reliable, but not have all 
            the latest features), or the current version (which will be 
            less reliable, but have more features). Choose according to 
            your own situation.</para>

            <para>
            	The install wizard gives you the opportunity to install
            	the latest "JRE" (Java Runtime Environment). There is no
            	need to select this if you already have a Sun Java
            	installed, version 5 or better.
            </para>

          </sect3>

          <sect3>

            <title>Downloading the Binary Executable</title>

            <para>If you choose to download the binary executable, you 
            will have a choice of downloading the latest stable version 
            of the code (which will be more reliable, but not have all 
            the latest features), or the current version (which will be 
            less reliable, but have more features). Choose according to 
            your own situation.</para>

            <para>ArgoUML comes in <literal>.zip</literal> or <literal>
            tar.gz</literal> flavors. Choose the former if you are a 
            Microsoft Windows user, and the latter if you are running 
            some flavor of Unix. 
            There is also a Mac OS X version with <literal>.app.tgz</literal> extension.
            Unpacking is as follows.
            </para>

            <itemizedlist>

              <listitem>

                <para>On Windows. Unzip the <literal>.zip</literal> 
                file with WinZip, or if your version of Windows 
                supports it,
                copy the files out of the compressed folder and put 
                them into a directory of your choosing.</para>

              </listitem>

              <listitem>

                <para>On Unix. Use GNU tar to unzip and break out the 
                files to a directory of your choice <literal>
                tar&nbsp;zxvf&nbsp;&lt;file&gt;.tar.gz</literal>. If you have an 
                older version of tar, the <literal>z</literal> option 
                may not be available, so use <literal>
                gunzip&nbsp;&lt;&nbsp;file.tar.gz&nbsp;|&nbsp;tar&nbsp;xvf&nbsp;-</literal>.</para>

              </listitem>

            </itemizedlist>

            <para>You should have a directory containing 
            a number of <literal>.jar</literal> files and a 
            <literal>README.txt</literal>.</para>

          </sect3>

          <sect3 id="s4.probsolving">

            <title>Problems Downloading and Installing</title>

            <para>If you get completely stuck and you have no local 
            assistance, try the web site, particularly the 
            <ulink url="http://argouml.tigris.org/faqs/users.html">
            FAQ</ulink>. If this still doesn&apos;t solve the problem, 
            try the ArgoUML users&apos; mailing list.</para>

            <para>You can subscribe through the mailing lists section 
            of the project web site 
            <ulink url="http://argouml.tigris.org">
            argouml.tigris.org</ulink>, or send an empty message to 
            <ulink url="mailto:users@argouml.org">
            users@argouml.org</ulink> with the subject line <literal>
            subscribe</literal>.</para>

            <para>You can then send your problem to 
            <ulink url="mailto:users@argouml.org">
            users@argouml.org</ulink> and see how other users are able 
            to help.</para>

            <para>The users&apos; mailing list is an excellent 
            introduction to the live activity of the project. If you 
            want to get further involved there are additional mailing 
            lists that cover the development of the product and issues 
            in the current and future releases.</para>

          </sect3>

          <sect3>

            <title>Running ArgoUML</title>

            <para>To run ArgoUML depends on whether you use Microsoft 
            Windows or some flavor of Unix.</para>

            <itemizedlist>

              <listitem>

                <para>
                  On Windows. If you used the installer, starting ArgoUML is a matter of clicking on its icon.
                  In case you installed the binairy executable, read on:
                  Start an MSDOS shell window by e.g. 
                  using Start/Run with <quote>command</quote> in the text window.
                  In the window change to the directory holding your ArgoUML files
                  and type <literal>java -jar argouml.jar</literal>.
                  This method has the advantage that progress and debugging
                  information is visible in the DOS window. 
                  Alternatively use the supplied batch file (.bat), 
                  or create one containing the above
                  command, with a shortcut to it on the desktop.
                  The batch file should end with a "pause" statement in case any
                  debugging information is created during a run.
                  On some systems, simply (double) clicking on the
                  <literal>argouml.jar</literal> file works.
                  On others doing so initiates a zip utility.
                  Refer to your operating system instructions or help facility
                  to determine how to configure this.
                </para>

              </listitem>

              <listitem>

                <para>
                  On Unix. Start a shell window and type
                  <literal>java -jar argouml.jar</literal>
                </para>

              </listitem>

            </itemizedlist>

          </sect3>

          <sect3>

            <title>Problems Running ArgoUML</title>

            <para>
              It&apos;s unusual to encounter problems if you have made a successful
              download.
              If you can&apos;t solve the problem. Try the users&apos; mailing list
              (see <xref linkend="s4.probsolving"/>).
            </para>

            <itemizedlist>

              <listitem>

            <para>
              Wrong JRE.
              The most common issue is not having a new enough
              Java Runtime Environment (it must be version 5 or  later).
            </para>

              </listitem>

              <listitem>

                <para>
                  Wrong language.
                  If the product came up in a language you can&apos;t read or just
                  don&apos;t want, go to the second leftmost menu item in the
                  menu bar at the top of the screen.
                  Select the bottom most menu entry in the drop down.
                  <xref linkend="fig.prob.run.02"/> shows this in Russian.
                  Then click on the second tab from the bottom in the column of
                  tabs on the left.
                  Drop down the list as shown in 
                  <xref linkend="fig.prob.run.02"/>
                  and select a language.
                  Note that the languages are listed in themselves.
                  The language shown as being selected is German in which the
                  word for <quote>German</quote> is <quote>Deutsch</quote>.
                  You will have to exit ArgoUML and restart it for the change to
                  take effect.
                  Use the X button at the upper right.
                </para>

              </listitem>

            </itemizedlist>

            <figure float="1" id="fig.prob.run.01">

              <title>Finding the Settings Wizard</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/langprob01.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <figure float="1" id="fig.prob.run.02">

              <title>Setting Language in the Appearance Pane</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/langprob02.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>
          </sect3>

        </sect2>

        <sect2 id="tut.user.iface">

          <title>The ArgoUML User Interface</title>

          <para>
            Before beginning the Case Study, you need to become familiar with the
            user interface.
            Start by reading the introduction to the User Interface Reference.
            See <xref linkend="ch.ref.ui"/>.
            You should also read the <xref linkend="s1.ref.mouse"/>
          </para>

          <para>
            As you go through this tutorial you will be told what to do, and when
            to do it but how to do it will often be left to the
            User Interface Reference.
            It is not necessary at this point to read all of the Reference, but you
            should leaf through enough of it to become familiar with how to find
            things in it.
            Every attempt will be made to direct you to the appropriate part of the
            Reference at those points in the tutorial where they apply.
          </para>

          <para>
            <xref linkend="fig.tut.startup"/>, shows the main ArgoUML window as it
            appears when ArgoUML is first entered.
          </para>

          <figure float="1" id="fig.tut.startup">

            <title>Initial ArgoUML window</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/tutorial/startup.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>

          </figure>

          <para>
            Grab the vertical divider bars and move them back and forth.
            Grab the horizontal divider bar and move it up and down.
            Play around a little with the little arrows at the left or top of the
            divider bars.
            See <xref linkend="s1.ref.panes"/>.
          </para>

          <sect3 id="tut.menu.toolbars">

            <title>The Menu Bar and Toolbars</title>

            <indexterm><primary>Menu Bar</primary></indexterm>
            <indexterm><primary>Toolbars</primary></indexterm>
            <para>
              The menu bar and toolbars give access to all the 
              main features of ArgoUML.
              As is conventional, menu options and toolbar options that are not
              available (disabled) are grayed out and menu items that invoke a
              dialog box are followed by an ellipsis (...).
              At this time you should read <xref linkend="ch.ref.toolbar"/>
              and <xref linkend="ch.ref.menu"/>.
            </para>

            <para>
              <emphasis>File</emphasis> menu.
                  <indexterm><primary>File Menu</primary></indexterm>
                  The standard file menu entries present no surprises and we
                  will just use them when needed without first showing how they
                  work.
                  A number of other actions are available that are peculiar
                  to ArgoUML and we will go over them here.
            </para>

            <orderedlist>

              <listitem>

                    <para>
                      <emphasis>File=&gt;Revert to Saved.</emphasis>
                      This has the same effect as File=&gt;Open Project selecting the
                      current project.
                    </para>

              </listitem>

              <listitem>

                    <para>
                      <emphasis>Export/Import.</emphasis>
                      Select the project line at the top of the Explorer.
                      It should say "untitledModel" unless you have
                      changed it.
                      Perform a
                      <emphasis>File=&gt;Export XMI</emphasis> action
                      using "DeleteThis" for an output name in the file
                      chooser dialog.
                      Select the "Properties" tab in the "Details Pane" and
                      change the name to something else, anything will do.
                      Perform a
                      <emphasis>File=&gt;Import XMI</emphasis> action.
                      It will ask you whether you want to save the changes
                      you have just made.
                      Click on "No" and then in the file choosed that
                      comes up select the "DeleteThis.xmi" file that you
                      just wrote out.
                      Observe that the name of the model has reverted back
                      to what you had saved.
                    </para>

              </listitem>

              <listitem>

                    <para>
                      <emphasis>File=&gt;Import Sources.</emphasis>
                      We will cover this later.
                      You can&apos;t test it now unless you have some Java
                      source code of your own handy.
                    </para>

              </listitem>

              <listitem>

                    <para>
                      <emphasis>File=&gt;Export (All) Graphics.</emphasis>
                      In the Explorer Pane select one of the diagrams.
                      Either "Class Diagram 1" or "Use Case Diagram 1"
                      (assuming you haven&apos;t renamed or deleted them).
                      Perform a
                      <emphasis>File=&gt;Export Graphics</emphasis> action.
                      When the file chooser opens it defaults to the last
                      name you saved something to
                      (even from a project no longer open).
                      The file chooser allows you to select from a number
                      of formats.
                      Drop down the "Files of type" combobox and observe
                      the choices.
                      Cancel out as there is nothing useful to save.
                      Perform a
                      <emphasis>File=&gt;Export All Graphics</emphasis>
                      action.
                      Notice that this time you can&apos;t specify a file
                      name and you can&apos;t select a file format.
                      ArgoUML will allow you only to select an output
                      directory.
                      It will then create a file for each of your diagrams
                      using the diagram name for the file name and an
                      extension determined by the default graphics format.
                      Actually, although you can&apos;t select file names
                      in the browser panel, you can type one into the
                      edit box.
                      But, if you do that, nothing at all will happen.
                      You will learn more about the default graphics format
                      when we get to the <emphasis>Edit</emphasis> menu.
                    </para>

              </listitem>

              <listitem>

                    <para>
                      <emphasis>File=&gt;Notation.</emphasis>
                      We are going to get a little ahead of ourselves here
                      and do a little class diagram work so you can see
                      what notation is all about.
                      In the Explorer Pane select or create a class diagram.
                      See <xref linkend="s1.ref.create.diagram.menu"/> and
                      <xref linkend="s2.ref.edit_pane_drawing_tools"/>.
                      Create a class in the diagram.
                      Go to the Detail Pane and create an attribute
                      in the class.
                      See <xref linkend="s2.ref.class_property_toolbar"/>.
                      In the Properties tab of the Detail Pane change the
                      multiplicity to "1..*".
                      Now go the the <emphasis>File Menu</emphasis>
                      and select <emphasis>Notation</emphasis>.
                      Go back and forth between UML and Java observing
                      the changes in the display in the Edit Pane.
                    </para>

              </listitem>

              <listitem>

                    <para>
                      <emphasis>File=&gt;Project Properties.</emphasis>
                      In the Project Properties dialog it is possible to
                      configure the project specific settings.
                      It contains the tabs for User, Profiles, Notations and
                      Diagram Appearance.
                      For instance, to change the Notation language in the
                      Project Properties dialog, click on
                      <emphasis>File=&gt;Project Properties</emphasis> and select
                      the Notations tab.
                      Set the Notation Language to UML1.4.
                      Turn on all of the options and click Apply.
                      Then turn off all of the options and click Apply
                      observing the changes in the diagram.
                      Set the Default Shadow Width to 8 and click Apply.
                      Notice that nothing happens.
                      This is because you are not setting the Shadow Width,
                      but its default.
                      The next time you create a class in a diagram, this
                      new shadow value will apply.
                    </para>

              </listitem>

            </orderedlist>

            <para>
              <emphasis>Edit</emphasis> menu.
                  <indexterm><primary>Edit Menu</primary></indexterm>
                  The edit menu does not look like what you are used to
                  in other products.
                  There are no "Cut", "Copy", or "Paste" actions.
                  All of the choices are peculiar to ArgoUML so we are
              going to cover all of them in detail.
            </para>

            <orderedlist>

              <listitem>

                <para>
                  <emphasis>Edit=&gt;Select.</emphasis>
                </para>
                <itemizedlist>
                  <listitem>
                    <para>
                      Select a class diagram in the Explorer Pane.
                      If there is none there create one using
                      <emphasis>Create=&gt;New Class Diagram</emphasis>.
                      Create three classes using the class tool described
                      in the User Interface Reference section on
                      Class Diagram Specific Tools.
                      Double click on it and then click in the Edit Pane
                      for the class diagram in three different locations.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Undo the current mode by clicking on the "Select" tool.
                      See <xref linkend="s2.ref.edit_layout"/>.
                      This allows you to do things in the Edit Pane other
                      than creating classes.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Open everything in the Explorer Pane tree, 
                      so that all elements are visible.
                      Now activate the first menu item:
                      <emphasis>Edit=&gt;Select=&gt;All</emphasis>.
                      Obviously, this selects all elements, 
                      but only those on the current diagram - elements 
                      only present on another diagram are not selected this way.
                      This function is e.g. usefull if you have a big diagram, 
                      and need to shift everything 
                      to add some more elements 
                      at the left or top of the diagram.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Each of the classes in the diagram has three vertically
                      spaced sections.
                      Double click in the top section of each class and
                      enter a name for the class then hit the enter key.
                      Just name the classes "A", "B", and "C".
                      Select class A, then class B, and then class C either
                      in the Edit Pane or in the Explorer Pane.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Now do an
                      <emphasis>Edit=&gt;Select=&gt;Navigate Back</emphasis>.
                      Class B should now be selected.
                      Do another
                      <emphasis>Edit=&gt;Select=&gt;Navigate Back</emphasis>.
                      Class A should now be selected.
                      Finally, do an
                      <emphasis>Edit=&gt;Select=&gt;Navigate Forward</emphasis>.
                      Class B should be selected again.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Do an
                      <emphasis>Edit=&gt;Select=&gt;Invert Selection</emphasis>.
                      Classes A and C should now be selected.
                      Do another
                      <emphasis>Edit=&gt;Select=&gt;Invert Selection</emphasis>.
                      Class B should be selected again.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Do an
                      <emphasis>Edit=&gt;Remove From Diagram</emphasis>.
                      Notice that class B is gone from the diagram but still
                      exists in the Explorer Pane.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      Select class B in the Explorer Pane, right click on it
                      and choose "Add to Diagram".
                      Move the cursor back onto the Edit Pane and left click on
                      some part of the diagram where you think it will fit.
                      You should be pretty much right back where you were before
                      you removed it from the diagram.
                      Do an
                      <emphasis>Edit=&gt;Delete From Model</emphasis>.
                      Now class B should be gone both from the diagram and from
                      the Explorer Pane.
                    </para>
                  </listitem>
                </itemizedlist>
              </listitem>
              <listitem>
                <para>
                  <emphasis>Edit=&gt;Configure Perspectives</emphasis>.
                  Read <xref linkend="s1.ref.configure_perspectives"/>.
                  We aren't going to go into this at this point as it needs
                  much larger projects to be displayed than we have available
                  at this point.
                </para>
              </listitem>
              <listitem>

              <figure float="1" id="fig.tut.settings.preferences">

              	<title>Initial ArgoUML window</title>

              	<screenshot>
              		<mediaobject>
              			<imageobject>
              				<imagedata align="center"
              					fileref="images/tutorial/settings-preferences.png" format="PNG" />
              			</imageobject>
              		</mediaobject>
              	</screenshot>

              </figure>

              <para>
                  <emphasis>Edit=&gt;Settings=&gt;Preferences</emphasis>.
                  Enter Help=&gt;About ArgoUML.
                  Look at the panel in the "splash" tab.
                  This is known as the Splash Panel.
                  Go to Edit=&gt;Settings=&gt;Preferences.
                  Turn off the "Show Splash Panel"
                  check button.
                  Exit from ArgoUML and restart it.
                  Note that the splash panel does not show during the load.
                </para>
              </listitem>

              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Environment</emphasis>.
                Do <emphasis>File=&gt;Export Graphics</emphasis> and observe
                the file extension that shows at the bottom of the file chooser
                dialog in the "Files of type" combobox.
                Go to the <emphasis>Edit=&gt;Settings=&gt;Environment</emphasis>
                editor and pick some other value for Default graphics format.
                Click "Apply" and then "OK".  Go back to the
                <emphasis>File=&gt;Export Graphics</emphasis> dialog and notice
                that the new format is now the default.
              </para></listitem>

              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;User</emphasis>.
                Enter your name and email address.
              </para></listitem>

              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Appearance</emphasis>.
                Change the "Look and Feel:" to Metal."
                Note that the "Metal Theme:" editor becomes anabled.
                Change the theme to "Very Large Fonts."
                Click on "Apply" and then "OK."
                Notice that nothing has happened.
                Exit from ArgoUML and reopen it.
                The display should be markedly different.
                You can change it back or leave it that way as you prefer. 
              </para></listitem>
                
              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Profiles</emphasis>.
                Look in the Explorer Pane under "Profile Configuration". 
                The only folder by default is the UML 1.4 profile. 
                Now go to <emphasis>Edit=&gt;Settings=&gt;Profiles</emphasis>
                and look at the field "Default Profiles". 
                It only contains the same UML 1.4 profile.
                Add the Java profile to it, and press OK.
              </para>
              <para>
                If you now look at the Explorer Pane, nothing has changed, 
                since you adapted the default setting, not the project setting.
                Press <emphasis>File=&gt;New</emphasis> and
                check out the profiles in the Explorer Pane: 
                it now shows both the UML 1.4 profile and the Java profile.
              </para>
              <para>
                Many examples in this manual presume that the Java profile is available,
                so you may best leave it enabled.              
              </para></listitem>
                
              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Configure Shortcuts</emphasis>.
                (To be written).
                <!-- Does not work - see issue 5207. -->
              </para></listitem>

              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Notations</emphasis>.
                We played around with this earlier with the
                <emphasis>File=&gt;Notation</emphasis> and
                <emphasis>File=&gt;Project Properties</emphasis> menu items.
                Start another copy of ArgoUML resize each copy so they can
                be seen at the same time next to each other.
                On one of them set the Notation Language to UML
                (the actual choice will have a version number with it).
                On the other  set the Notation Language to Java.
              </para>
              <para>
                On both of them do the following.
                Turn all of the check boxes on.
                Do a <emphasis>File=&gt;New</emphasis>, create a class in
                a class diagram.
                Double click in the attributes section to create an attribute.
                Double click in the operation section to create a method.
                Observe the difference in the displays.
              </para></listitem>

             <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Diagram Appearance</emphasis>.
                This settings makes it possible to change the font and font-size used in the diagrams. 
                Hence this setting does not influence the font used in the UI of ArgoUML itself.
                The default font for ArgoUML is Dialog.
              </para></listitem>

              <listitem><para>
                <emphasis>Edit=&gt;Settings=&gt;Modules</emphasis>.
                This shows the currently loaded modules.
                We are not going to mess with it in this version of the
                tutorial.
              </para></listitem>
            </orderedlist>

            <para>
              <emphasis>View</emphasis> menu.
              <indexterm><primary>View Menu</primary></indexterm>
              This allows you 
              to switch between diagrams, find model elements in the 
              model, zoom in a diagram, adjust the 
              grid, toggle page break display, and show an XML
              representation of the project.
              Do a <emphasis>File=&gt;New</emphasis> to get back to a
              known point.
              Create an example of each diagram type not already in the
              Explorer Pane.
              Click on the (+) sign widgets in the Explorer Pane to expand
              the tree nodes.
              Select the class diagram and give it a name.
            </para>

            <orderedlist>
              <listitem><para>
                <emphasis>View=&gt;Goto Diagram</emphasis> brings up a
                Go To Diagram panel.
                Select the class diagram entry in this panel and click on
                the "Go to Selection" button.
                There should be 0 nodes and 0 edges in the description column.
                Click on the "Close" button.
                In the Details Pane (Properties tab) enter the name as "Blort".
                Create two classes <!--  (See ...)--> in the class diagram and go
                back to <emphasis>View=&gt;Goto Diagram</emphasis>.
                You should now see 2 nodes and 0 edges shown.
                Click on the "Close" button again and link the classes with
                one of the "line" items like association or generalization.
                Go back to <emphasis>View=&gt;Goto Diagram</emphasis> and you
                should see 2 nodes and 1 edge(s).
                Click on the "Close" button again and create a third class.
                Run the mouse over the icons in the toolbar until you find the
                one with the tooltip "New Association Class."
                Click on this tool and then connect the new class to one
                of the others.
                Having clicked on the "New Association Class" tool move the
                mouse over the new class.
                Press and hold down button&nbsp;1.
                Move the mouse over one of the other classes and
                release button&nbsp;1.
                Go back to <emphasis>View=&gt;Goto Diagram</emphasis> and you
                should see 3 nodes and 2 edge(s).
                Even though it is a class and has a two dimensional
                representation, it counts as an edge not a node.
                Select other entries in this panel and click on
                the "Go to Selection" button in the Go To Diagram panel.
                Observe the changes in the Explorer Panel.
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;Find.</emphasis>
                At this point you should have three normal classes and an
                association class in the Explorer Pane.
                Name them "AA", "AB", "B", and "C".
                Perform a <emphasis>View=&gt;Find</emphasis> operation.
                Click on the "Find" button.
                Notice that an "* in *" tab is created below.
                This tab should show pretty much everything.
                In the "In Diagram" editor change the "*" to "B*" and
                click on the "Find Button" observing the contents of the
                new tab with "* in B*" as a tab label.
                You should see the three classes, the link (such as an
                association), and the association class.
                In the Element Type drop down box select "Interface" and click
                on the Find button.
                The new tab "* in B* Inte..." should have no entries in it
                as we have defined no interfaces.
                In the Element Type drop down box select "Class" and click
                on the Find button.
                The new tab "* in B* Class" should have one fewer entries
                in it than the "* in B*" tab.
                Switch back and forth between these two
                observing the difference.
                In various of these tabs select an item and click on the
                "Go To Selection" button observing the change in the selection
                shown in the diagram and in the Explorer Pane.
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;Zoom.</emphasis>
                As an exeption to a general rule the toolbar equivalent of
                <emphasis>View=&gt;Zoom</emphasis> does not operate in the
                same way as the corresponding menu item.
                Highlight <emphasis>View=&gt;Zoom.</emphasis> and a submenu
                will appear that contains "Zoom Out", "Zoom Reset" and
                "Zoom In".
                Click on these a few times observing the effect on the
                diagram then click on the Zoom tool bar icon.
                This is a magnifying glass next to a down arrow head.
                You should see a graduated slider bar tool.
                Grab the pointer in this tool and move it up and down
                observing the effect on the diagram.
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;Adjust Grid.</emphasis>
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;Adjust Snap.</emphasis>
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;Page Breaks.</emphasis>
              </para></listitem>
              <listitem><para>
                <emphasis>View=&gt;XML Dump.</emphasis>
              </para></listitem>
            </orderedlist>

                <para><emphasis>Create Diagram</emphasis> menu. This 
                <indexterm><primary>Create Diagram Menu</primary></indexterm>
                allows you to create any one of the seven UML diagram 
                types (class, use case, state, activity, collaboration, 
                deployment and sequence) supported by ArgoUML.</para>

                <para>State and activity diagrams can only be created 
                when a class or actor is selected, even though the 
                relevant menu entries are <emphasis>not</emphasis> 
                grayed out if this has not been done (nothing will 
                happen under this circumstance).</para>

                <para><emphasis>Arrange</emphasis> menu. This allows 
                <indexterm><primary>Arrange Menu</primary></indexterm>
                you to align, distribute and reorder model elements 
                on a diagram and set the layout strategy for the 
                diagram.</para>

                <para><emphasis>Generation</emphasis> menu. This allows 
                <indexterm><primary>Generation Menu</primary></indexterm>
                you to generate Java code for selected classes or all 
                classes.</para>

                <para><emphasis>Critique</emphasis> menu. This allows 
                <indexterm><primary>Critique Menu</primary></indexterm>
                you to toggle the auto-critique on and off, set the 
                level of importance of design issues and design goals 
                and browse the critics available.</para>

                <para><emphasis>Tools</emphasis> menu. This menu is 
                <indexterm><primary>Tools Menu</primary></indexterm>
                permanently grayed out unless there is some tool 
                available in your version of ArgoUML.</para>

                <para><emphasis>Help</emphasis> menu.
                <indexterm><primary>Help Menu</primary></indexterm>
                This menu gives 
                access to details of those who authored the system, and 
                where additional help may be found.</para>

                <para>File Toolbar.
                <indexterm><primary>File Toolbar</primary></indexterm>
                This toolbar contains some of the 
                tools from the File menu.</para>

                <para>Edit Toolbar.
                <indexterm><primary>Edit Toolbar</primary></indexterm>
                This toolbar contains some of the 
                tools from the Edit menu.</para>

                <para>View Toolbar.
                <indexterm><primary>View Toolbar</primary></indexterm>
                This toolbar contains some of the 
                tools from the View menu.</para>


                <para>Create Diagram Toolbar.
                  <indexterm>
                    <primary>Create Diagram Toolbar</primary>
                  </indexterm>
                  This toolbar contains 
                  some of the tools from the Create Diagram menu.
                </para>

          </sect3>
          <sect3>

            <title>The Explorer Pane</title>

            <para>
              At this time you should take the time to read
              <xref linkend="ch.ref.navpane"/>.
              The Explorer Pane is fundamental to almost everything that you do
              and we will be coming back to it again and again in what follows.
              In fact you will recall we have had to use it already.
            </para>

            <para>
              There is an expand or contract control in front of the package
              symbol for <quote>untitledModel</quote> in the Explorer Pane and
              the package symbol for <quote>Medium</quote> in the To-Do Pane.
              Click on these controls and observe that these panes are tree widgets
              that behave pretty much as you would expect them to.
              The expand or contract control is either plus (+)/minus (-) sign
              or knob with a right or bottom pointer depending upon the look and
              feel that you have chosen for an appearance.
            </para>

            <para>
              Select alternately Class Diagram 1 and Use Case Diagram 1  observing
              that the detail pane changes to track to the selected item in the
              Explorer.
              The detail pane is described in Chapter 12.
              It is not necessary to read Chapter 12 at this point, but it
              couldn&apos;t hurt.
            </para>

          </sect3>

          <sect3>

            <title>The Editing Pane</title>

            <para>
              At this point take some time to read
              <xref linkend="ch.ref.editpane"/>.
            </para>

            <para>
              As we go through the Editing pane changes will sometimes occur
              in the Details and the To-Do panes.
              Pay no attention to them for now.
              We will attend to them when we cover those panes.
            </para>
            <para>
              Select "Class Diagram 1" in the Explorers Pane.
              The name is unimportant, if you have changed it, just select
              the new name.
              If you have deleted it, first perform a 
              Create=&gt;New Class Diagram action.
              Click on the "New Package" button in the Edit Pane tool bar.
              Click somewhere in the edit pane.
              In the Explorer notice that a package appears named
              (unnamed Package).
            </para>
            <para>
              Double click on the "New Class" button in Edit Pane the tool bar.
              Click first within the package and once outside of it.
              Notice that within the Explorer, two classes appear in the tree
              both named (unnamed Class) one of them attached to the model node
              and the other attached to the (unnamed Package) node.
            </para>
            <para>
              Click the Select button in the Edit Pane tool bar so you can do
              things in the Edit Pane without adding new Classes.
              In the Explorer select the class that is not subordinate to the
              package.
              This selects the corresponding class in the diagram.
              Grab this class and move it into the package.
              Notice that in the Explorer this class is now also subordinate
              to the package node.
            </para>
            <para>
              In the diagram select the other class.
              Notice that in the Explorer, the selected node
              changes correspondingly.
              Grab this class and move it outside of the package and watch
              what happens in the Explorer.
            </para>

          </sect3>

          <sect3>

            <title>The Details Pane</title>

            <para>
              At this point take some time to read
              <xref linkend="ch.ref.detpane"/>.
            </para>

            <note>

              <itemizedlist>

                <listitem><para>To-Do Item.
                  Discuss differences with other tabs about locations of
                  items selected.
                  Hold particulars for discussion of To-Do Pane.</para></listitem>

                <listitem><para>Properties,</para></listitem>

                <listitem><para>Documentation,</para></listitem>

                <listitem><para>Presentation,</para></listitem>

                <listitem><para>Source,</para></listitem>

                <listitem><para>Constraints,</para></listitem>

                <listitem><para>Stereotype,</para></listitem>

                <listitem><para>Tagged Values,</para></listitem>

                <listitem><para>Checklist.</para></listitem>

                <listitem><para>
                  Remove "images/tutorial/detailsoverview.gif" from file system.
                </para></listitem>

              </itemizedlist>

            </note>

          </sect3>

          <sect3>

            <title>The To-Do Pane</title>

            <para>
              At this point take some time to read
              <xref linkend="ch.ref.todopane"/>.
            </para>

            <note>

              <itemizedlist>

                <listitem><para>Describe priorities.</para></listitem>

                <listitem><para>Resolving items.</para></listitem>

                <listitem><para>Relation to ToDo Item tab in details pane.
                </para></listitem>

                <listitem><para>
                  Remove "images/tutorial/todooverview.gif" from file system.
                </para></listitem>

              </itemizedlist>

            </note>

          </sect3>

          <!-- sect3 id="s3.tut.mouse">

            <title>The Mouse</title>

            <para>The mouse and mouse buttons (or their equivalent with 
            alternative tracking devices) are used in a wide variety of 
            ways. In this section we look at the common modes of 
            use.</para>

            <para>ArgoUML assumes a two button mouse. We will refer to 
            the buttons as <quote>button&nbsp;1</quote> and <quote>button 
            2</quote>. Button&nbsp;1 is the leftmost button on a 
            right-handed mouse, and sometimes referred to as the 
            <quote>select</quote> button. Button&nbsp;2 is sometimes 
            referred to as the <quote>adjust</quote> button.</para>

            <orderedlist>

              <listitem>

                <para><emphasis>Button&nbsp;1 click</emphasis>. This action 
                is generally used to select an item for subsequent 
                operations. If the item is a model element in the explorer 
                or the editing pane it will be highlighted.</para>

                <para>In the case of the Edit Pane Toolbar, that 
                model element is selected as the next to be added to the 
                diagram (but only once&mdash;see double clicking for adding 
                multiple model elements). The adding to the diagram is 
                achieved by moving the mouse to the editing area and 
                clicking again.</para>

              </listitem>

              <listitem>

                <para><emphasis>Button&nbsp;1 double click</emphasis>. This 
                action is identical to a single click 
                <emphasis>except</emphasis>, when it is used with the 
                edit pane toolbar. Under these circumstances the 
                selected model element will be added multiple times to the 
                drawing area, once for each further button click, until 
                the tool is again selected or another tool 
                chosen.</para>

              </listitem>

              <listitem>

                <para><emphasis>Button&nbsp;2 click</emphasis>. When used 
                over text items in the the explorer or details panes, 
                or graphical model elements in the editing pane, this will 
                display a context dependent drop-down menu.</para>

                <para>If the item has not yet been selected it will 
                also be selected.</para>

              </listitem>

              <listitem>

                <para><emphasis>Button&nbsp;1 motion</emphasis>. Where 
                button&nbsp;1 click has been used to pull down a menu from 
                the menu bar, button&nbsp;1 motion is used to select items 
                on that menu.</para>

                <para>Button&nbsp;1 motion also has an effect in the editing 
                pane. Over graphical model elements it will move the 
                model element to a new position. Graphical model elements that 
                are selected show handles, and these can be used for 
                re-sizing.</para>

                <para>Where the model element is some form of connector 
                between other items, button&nbsp;1 motion other than at a 
                handle will cause a new handle to be created, allowing 
                the connector to be articulated at that point. Such new 
                handles can be removed by moving them to the end of the 
                connector.</para>

              </listitem>

              <listitem>

                <para><emphasis>Button&nbsp;2 motion</emphasis>. This is 
                used to select items in a context sensitive menu popped 
                up by use of button&nbsp;2 click.</para>

              </listitem>

            </orderedlist>

            <para>There are other more specific behaviors that will be 
            encountered under the specific cases where they are 
            used.</para>

          </sect3-->

          <sect3>

            <title>Drawing Diagrams</title>

            <para>In general diagrams are drawn by using the edit pane 
            toolbar to select the model element desired and clicking in the 
            diagram at the position required.</para>

            <para>Model elements that are already in the model, but not on a 
            diagram, may be added to a diagram by selecting the 
            model element in the explorer, using <literal>
            Add to Diagram</literal> from the drop down menu (button&nbsp;2) 
            over that model element, and then clicking button&nbsp;1 at the 
            desired location on the diagram.</para>

            <para>As well as UML model elements, the Edit pane toolbar 
            provides for general drawing objects (rectangles, 
            circles, lines, polygons, curves, text) to provide 
            supplementary information on diagrams.</para>

            <sect4>

              <title>Moving Diagram Elements</title>

              <para>There are several ways to move diagram 
              elements.</para>

              <sect5>

                <title>Using the Mouse Keys</title>

                <para>Select the elements you want to move. By holding 
                down the Ctrl key while selecting you can select several
                elements to move at the same time.</para>

                <para>Now hit your arrow keys. Your elements move a 
                little with every key stroke.</para>

                <para>If you also hold down the Shift key, they move a 
                bit faster.</para>

              </sect5>

              <sect5>

                <title>Using the Edit Pane Toolbar</title>

                <para>Click on the broom button on the toolbar. Move 
                your mouse to the diagram pane, right click and hold. 
                Now moving your mouse will align elements.</para>

              </sect5>

            </sect4>

            <sect4>

              <title>Arranging Elements</title>

              <para>The menu item <literal>Arrange</literal> allows you 
              to align or group elements.</para>

            </sect4>

          </sect3>

          <sect3>

            <title>Working with Projects</title>

            <sect4>

              <title>The Start-Up Window</title>

              <para><xref linkend="fig.tut.startup"/> shows the ArgoUML 
              main window as it appears as right after start-up</para>

              <!--figure float="1" id="fig.tut.startup">

                <title>ArgoUML Window at Start-Up</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/startup.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure-->

              <para>The main window&apos;s client area, below the menu 
              and toolbar, is subdivided into four panes. Starting at 
              the leftmost top pane, and working around the clock, you 
              can see the Explorer, showing a tree view of your UML 
              model, the Editing Pane with its toolbar, two scroll bars 
              and gray drawing area, the Details Pane with the ToDoItem 
              tab selected, and the To-Do Pane with a tree view of the 
              to do items, ranked in various ways selected via the drop 
              down list at the top of the pane.</para>

              <para>Each time ArgoUML is started up without a project 
              file as an argument, a new blank project is created. This 
              project contains a model called <literal>
              untitledModel</literal>. This model contains a blank 
              Class Diagram, called <literal>class diagram 1</literal>, 
              and a blank Use Case Diagram called <literal>
              use case diagram 1</literal>.</para>

              <para>The model and both empty diagrams can be seen in 
              the explorer, which is the main tool for you to navigate 
              through your model.</para>

              <para>Let&apos;s assume for a moment that this is the 
              point where you want to start modeling a new purchasing 
              system. You want to give the name 
              <quote>purchasingmodel</quote> to your model, and you 
              want to store it in a file called <literal>
              FirstProject</literal>.</para>

            </sect4>

            <sect4>

              <title>Saving a Project - The File Menu</title>

              <para>
                For now ArgoUML; saves diagrams using an earlier
                proposed standard, <emphasis>Precision Graphics Markup 
                Language (PGML)</emphasis>.
                However it has the option to export graphical data as SVG
                for those who can make use of it.
                When ArgoUML; supports UML 2.0, it will store
                diagrams using the UML 2.0 Diagram Interchange format.
              </para>

              <para>First, let&apos;s save the model in it&apos;s 
              current (empty and unnamed) state. On the menu bar, click 
              on <literal>File</literal>, then on <literal>
              Save Project As...</literal> as shown in 
              <xref linkend="fig.tut.saveas"/>.</para>

              <figure float="1" id="fig.tut.saveas">

                <title>Invoking
                <literal>Save Project As...</literal></title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/saveas.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>Please notice that the File menu contains the usual 
              options for creating a new project, for opening an 
              existing project, for saving a project under a new name, 
              for printing the currently displayed diagram, for saving 
              the currently displayed diagram as a file, and for 
              program Exit.</para>

              <para>Some of these menu commands can be invoked by 
              pressing key combinations, as indicated on the drop-down 
              menu. For instance, holding down the <quote>Ctrl</quote> 
              key, and pressing <quote>N</quote>, will create a new 
              project.</para>

              <para>In the current version, ArgoUML can only contain 
              one active project at a time. In addition, a project can 
              only contain one UML model. Since an UML model can 
              contain an unlimited number of elements and diagrams, 
              this should not present any serious limitations, even for 
              modeling quite large and complex systems.</para>

            </sect4>

            <sect4>

              <title>The File Chooser Dialog</title>

              <para>But let&apos;s go back to saving our project. After 
              clicking on the <literal>Save Project As...</literal> menu 
              command, we get the file chooser dialog to enter the file 
              name we wish to use as shown in 
              <xref linkend="fig.tut.filechoose"/>.</para>

              <figure float="1" id="fig.tut.filechoose">

                <title>File Chooser Dialog</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/filechoose.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>This is a standard Java FileChooser. Let&apos;s go 
              over it in some detail.</para>

              <para>The main, outstanding feature, is the scrollable 
              folders list in the center of the dialog. By using the 
              scroll bar on the right, you can move up and down in the 
              list of folders contained inside the currently selected 
              folder. If it is scrollable or not depends on the amount 
              of files and folders shown and also how they are shown. 
              If everything fits the window is not scrollable as seen 
              in the picture.</para>

              <para>Double-clicking on one of the displayed folders 
              navigates you into that folder, allowing you to quickly 
              navigate down into the folders hierarchy on your hard 
              disk.</para>

              <para>Notice that only folder names, and no file names 
              are displayed in the scrollable area. Indeed, the dialog 
              is currently set up in order to show only ArgoUML project 
              files with an extension of <literal>.zargo</literal>, as 
              can be seen on the lower drop-down control labeled 
              <literal>Files of Type:</literal>.</para>

              <para>Also notice that the currently selected 
              folder&apos;s name is displayed in the upper drop-down 
              control labeled <literal>Look in:</literal>. A single 
              click on a folder inside the scrollable area does select 
              that folder on screen but does not select the folder for 
              saving.</para>

              <para>At the top of the dialog, above the scrollable 
              folder chooser area, there are a few more folder 
              navigation tools.</para>

              <itemizedlist>

                <listitem>

                  <para><guiicon>
                  <inlinegraphic fileref="images/tutorial/guifolderdropdown.gif"
                   format="GIF"/></guiicon> The Folder drop-down 
                  control. Clicking on the down-arrow displays a tree 
                  view of the folder hierarchy, allowing you to 
                  navigate quickly up the hierarchy, and at the same 
                  time to quickly determine where in the hierarchy we 
                  are currently positioned.</para>

                </listitem>

                <listitem>

                  <para><guiicon>
                  <inlinegraphic fileref="images/tutorial/guifolderupicon.gif"
                   format="GIF"/></guiicon> The Folder-Up icon. 
                  Clicking on this icon will bring us to the parent 
                  folder of the current folder.</para>

                </listitem>

                <listitem>

                  <para><guiicon>
                  <inlinegraphic fileref="images/tutorial/guihomefoldericon.gif"
                   format="GIF"/></guiicon> The Home Folder icon. 
                  Clicking on this icon will bring us to our home 
                  directory.</para>

                </listitem>

                <listitem>

                  <para><guiicon>
                  <inlinegraphic fileref="images/tutorial/guinewfoldericon.gif"
                   format="GIF"/></guiicon> The New Folder icon. 
                  Clicking on this icon will create a new folder called 
                  &quot;New Folder&quot; under the current folder. 
                  After the folder is created selecting it an clicking 
                  in the name allows us to select the name of our 
                  choice.</para>

                </listitem>

                <listitem>

                  <para><guiicon>
                  <inlinegraphic fileref="images/tutorial/guifolderspresentationicon.gif"
                   format="GIF"/></guiicon> The Folders Presentation 
                  Icon.</para>

                </listitem>

              </itemizedlist>

              <para>OK, now we navigate to the directory where we want 
              to save our ArgoUML project, fill in the <literal>
              File name:</literal> with an appropriate name, such as 
              <quote>FirstProject</quote> and click on the <literal>
              Save</literal> button.</para>

              <para>You have now an active project called <literal>
              FirstProject</literal>, connected to the file <literal>
              FirstProject.zargo</literal>.</para>

            </sect4>

          </sect3>

        </sect2>

        <sect2>

          <title>Output</title>

          <sect3 id="s3.tut.loadsave">

            <title>Loading and Saving</title>

            <sect4>

              <title>Saving XMI files in ArgoUML</title>

              <indexterm><primary>XMI</primary></indexterm>
              <para>ArgoUML saves the diagram information in a PGML 
              file (with extension <literal>.pgml</literal>, the model 
              information in an XMI file (with extension <literal>
              .xmi</literal> and information about the project in a 
              file with extension <literal>.argo</literal>. See 
              <xref linkend="s4.tut.pgml"/> and 
              <xref linkend="s3.tut.xmi"/> for more about PGML and XMI 
              respectively.</para>

              <para>All of these are then zipped to a file with 
              extension <literal>.zargo</literal>. You can easily 
              extract the <literal>.xmi</literal> file from the 
              <literal>.zargo</literal> file using any old generic 
              <application>ZIP</application> application. Give it a try 
              and look into the magic of Argo.</para>

              <warning>

                <para>Be aware that double clicking will launch a 
                <literal>ZIP utility</literal>, if one is installed, 
                and NOT Argo.</para>

              </warning>

            </sect4>

          </sect3>

          <sect3>

            <title>Graphics and Printing</title>

            <sect4>

              <title>The Graph Editing Framework (GEF)</title>

              <para>GEF is the software package that is the foundation 
              of the diagrams that appear in the Editing Pane. GEF was 
              an integral part of ArgoUML but has been separated. Like 
              ArgoUML it is an open source project available via 
              <ulink url="http://www.tigris.org">Tigris</ulink>.</para>

            </sect4>

            <sect4 id="s4.tut.pgml">

              <title>Precision Graphics Markup Language (PGML)</title>

              <para>PGML is the current storage format for diagram information 
              used in ArgoUML. In the future, PGML will be replaced by
              the UML 2.0 Diagram Interchange format.</para>


            </sect4>

            <sect4>

              <title>Applications Which Open PGML</title>

              <para>PGML is a predecessor of SVG (see 
              <xref linkend="s4.tut.svg"/>. It was dropped by the W3C 
              Consortium.</para>

              <para>Currently there are no other tools that we know of 
              working on PGML.</para>

            </sect4>

            <sect4>

              <title>Printing Diagrams</title>

              <para>Select a diagram, then go to 
              <literal>File</literal>=&gt;<literal>Export Diagrams</literal>.
              You 
              can generate GIF, PostScript, Encapsulated PostScript or 
              SVG format.</para>

            </sect4>

            <sect4 id="s4.tut.svg">

              <title>Scalable Vector Graphics (SVG)</title>

              <para>A World Wide Web Consortium (W3C)
              standard vector graphics format
              (<ulink url="http://www.w3.org/TR/SVG/">
              http://www.w3.org/TR/SVG/</ulink>).</para>

              <para>Support is built in to modern browsers,
              but you can also get a plugin for older 
              browsers from <ulink url="http://www.adobe.com">
              adobe.com</ulink>.</para>

            </sect4>

            <sect4>

              <title>Saving Diagrams as SVG</title>

              <orderedlist>

                <listitem>

                  <para>Select <literal>.svg</literal> as the file 
                  type.</para>

                </listitem>

                <listitem>

                  <para>Type the name of the file as you like with the 
                  <literal>.svg</literal> tag at the end. Example 
                  <literal>myumldiagram.svg</literal></para>

                </listitem>

              </orderedlist>

              <para>Et viola! SVG! Give it a try and zoom around a 
              little... They are not pretty though, so if you know 
              anything about rendering beautiful SVG let us know.</para>

              <para>Most modern browsers support SVG.  If yours
              doesn&apos;t try <ulink url="http://www.mozilla.com/firefox/">
              Firefox</ulink> or get a plugin for your 
              current browser from 
              <ulink url="http://www.adobe.com">
              adobe.com</ulink></para>

              <note>

                <para>You will not have scroll bars for your SVG unless 
                it is embedded in HTML. Good luck and let us know 
                what you find!</para>

              </note>

            </sect4>

          </sect3>

          <sect3 id="s3.tut.xmi">

            <title>XMI</title>

            <indexterm><primary>XMI</primary></indexterm>
            <para>ArgoUML supports XMI 1.0, 1.1, and 1.2 files which
            contain UML 1.3 and UML 1.4 models.  For best compatibility
            with ArgoUML, export your models using UML 1.4 and XMI 1.1
            or 1.2.  Be sure to turn off any proprietary extensions
            (such as Poseidon&apos;s diagram data).</para>
            
            <para>With UML versions earlier than UML 2.0, it isn't
            possible to save diagram information, so no diagrams
            will be transferred.</para>

            <para>There is also a tool that converts XMI to HTML. For 
            more information, see 
            <ulink url="http://www.objectsbydesign.com/projects/xmi_to_html_2.html">
            http://www.objectsbydesign.com/projects/xmi_to_html_2.html</ulink>.</para>

            <sect4>

              <title>Using XMI from Rational Rose</title>

              <para>...</para>

            </sect4>

            <sect4>

              <title>Using Models Created by Poseidon</title>

              <indexterm><primary>XMI</primary></indexterm>
              <para>In the <literal>Export project to XMI</literal> dialog, but sure
              to clear the selection of <literal>Save with diagram data</literal>literal>.</para>

            </sect4>

            <sect4>

              <title>Using Models Created by MagicDraw</title>

              <para>...</para>

            </sect4>
            
            <sect4>

              <title>XMI Compatibility with other versions of ArgoUML</title>

              <para>Versions of ArgoUML prior to 0.19.7 supported
              UML 1.3/XMI 1.0.  After this time, the save format
              is UML 1.4/XMI 1.2 which is not backward compatible.
              Newer versions of ArgoUML will read projects written
              by older versions, but not vice versa.  If you might
              need to return to an older version of ArgoUML you should
              be careful to save a backup of your old projects.</para>
              
              <para>
                Additionally, if you write XMI files which 
                need to be read by other tools, you should take into
                account the different versions.
                Most modern UML
                modelling tools should read UML 1.4, but you may
                have in-house code generators or other tools which
                are tied to UML 1.3.
              </para>

            </sect4>

            <sect4>

              <title>Importing Other XMI Formats into ArgoUML</title>

              <para>XMI compatibility between UML modeling tools
              has improved over the years, but you may still
              occasionally run into problems.</para>
              
              <para>ArgoUML will not read XMI files which contain
              UML 1.5 or UML 2.0 models, but it should be able
              to open most UML 1.4 and UML 1.3 files.  If you find
              one that it can't open, please file a bug report
              so that a developer can investigate.</para>

            </sect4>

            <sect4>

              <title>Generating XMI Format</title>

              <para>Select the command
              <literal>File</literal>=&gt;<literal>Export as XMI</literal>
              and choose a 
              filename.</para>

            </sect4>

          </sect3>

          <sect3>

            <title>Code Generation</title>

            <sect4>

              <title>Code Generated by ArgoUML</title>

              <para>It is possible to compile your generated code with 
              ArgoUML, you still need to implement method bodies, 
              though, to get usable results.</para>

            </sect4>

            <sect4>

              <title>Generating Code for Methods</title>

              <para>At the moment you cannot write code for methods 
              (operations) within ArgoUML. The source pane is editable, 
              but the changes are ignored. ArgoUML is a pure design 
              tool for now, no IDE functionality but the desire is 
              there. You might consider using Forte and ArgoUML 
              together&mdash;it&apos;s a good work around!</para>

              <para>You can help us out there if you&apos;d like!</para>

            </sect4>

          </sect3>

        </sect2>

        <sect2>

          <title>Working With Design Critics</title>

          <para>
            Design critics are part of the practical application of the
            theories of Cognitive Psychology that are implemented in ArgoUML.
            See <xref linkend="tut.cog.psych"/>
          </para>

          <sect3>

            <title>Messages From the Design Critics</title>

            <para>Where do we stand now? A new project has been 
            created, and is stored in the file <literal>
            FirstProject.zargo</literal>. 
            <xref linkend="fig.tut.critstart"/> shows how your ArgoUML 
            window should look at this stage.</para>

            <figure float="1" id="fig.tut.critstart">

              <title>
                ArgoUML Window Having Saved
                <literal>FirstProject.zargo</literal>
              </title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/critstart.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>The project contains a top-level package, called 
            <literal>untitledModel</literal>, which contains a class 
            diagram and a use case diagram.</para>

            <para>If we look carefully at the screen, we can see that 
            the &quot;Medium&quot; folder in the To-Do Pane (the lower 
            left pane) must contain some items, since its activation 
            icon <guiicon>
            <inlinegraphic fileref="images/tutorial/guitreefoldercloseicon.gif"
             format="GIF"/></guiicon> is displayed.</para>

            <para>Clicking on this icon will open the 
            &quot;Medium&quot; folder. An open folder is indicated by 
            the <guiicon>
            <inlinegraphic fileref="images/tutorial/guitreefolderopenicon.gif"
             format="GIF"/></guiicon> icon.</para>

            <para>But what is this <quote>To-Do</quote> Pane anyway. 
            You haven&apos;t recorded anything yet that has to be done, 
            so where do these to do items originate.</para>

            <para>The answer is simple, and is at the same time one of 
            the strong points of ArgoUML. While you are working on your 
            UML model, your work is monitored continuously and 
            invisibly by a piece of code called a <emphasis>design 
            critic</emphasis>. This is like a personal mentor that 
            watches over your shoulder and notifies you each time he 
            sees something questionable in your design.</para>

            <para>Critics are quite unobtrusive. They give you a 
            friendly warning, but they do not force you into design 
            principles that you don&apos;t want or like to follow. Let 
            us take a look at what the critics are telling us. Click on 
            the <guiicon>
            <inlinegraphic fileref="images/tutorial/guitreefoldercloseicon.gif"
             format="GIF"/></guiicon> icon next to the <literal>
            Medium</literal> folder, and click on the <literal>
            Revise Package Name UntitledModel</literal> item.</para>

            <para><xref linkend="fig.tut.critrevname"/> shows how your 
            screen should now look.</para>

            <figure float="1" id="fig.tut.critrevname">

              <title>ArgoUML Window Showing the Critic Item <literal>
              Revise Package Name UntitledModel</literal></title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/critrevname.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>Notice that your selection is highlighted in red in 
            the To-Do Pane, and that a full explanation appears now in 
            the Details Pane (the lower right pane). You may have to 
            re-size your Details Pane or to scroll down in order to see 
            the full message as displayed in our example.</para>

            <para>What ArgoUML is trying to tell you is that usually, 
            package names are written in lower cases. The default top 
            level package created by ArgoUML is called <literal>
            untitledModel</literal> and therefore violates a sound 
            design principle. (Actually, this could be considered as a 
            bug within ArgoUML, but it comes in handy to demonstrate 
            the working of critics).</para>

            <para>At this point, you can choose to change the package 
            name manually or to impose silence on the design critic for 
            some time or permanently</para>

            <para>We will do nothing of this (we&apos;ll come back to 
            it when we talk about the design critics in more detail) 
            but we&apos;ll use another handy feature of ArgoUML&mdash;an 
            auto-correct feature.</para>

            <para>In order to do that, just click on the <literal>
            Next</literal> button on the Details Pane. This will cause 
            a renaming wizard to be displayed inside the properties 
            panel, proposing to use the name <literal>
            untitledmodel</literal> (all in lower case).</para>

          </sect3>

          <sect3>

            <title>Design Critics at Work: The Rename Package 
            Wizard</title>

            <para>Replace the name <literal>untitledmodel</literal> 
            with <literal>purchasingmodel</literal>, and click on the 
            <literal>Finish</literal> button. 
            <xref linkend="fig.tut.critwiz"/> shows how the ArgoUML 
            window will now look.</para>

            <figure float="1" id="fig.tut.critwiz">

              <title>ArgoUML Window Showing the Critic Wizard to Rename 
              the Package</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/critwiz.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>Watch now how the design critic note in the To Do 
            panel disappears, leaving only the <literal>
            Add Elements to Package purchasingmodel</literal> note in 
            the To-Do list.</para>

            <para>If this doesn&apos;t happen at once, wait for a few 
            seconds. ArgoUML makes heavy use of several threads of 
            execution that execute in parallel. This can cause delays 
            of a few seconds before the information gets updated on the 
            screen.</para>

            <para>The package name change should also be reflected in 
            the explorer, in the top left corner of your ArgoUML 
            window.</para>

            <para>We are now ready to create our first UML diagram, a 
            Use Case diagram, but first let&apos;s save what we&apos;ve 
            done so far.</para>

            <para>Click on the <literal>File</literal> menu item, and 
            select <literal>Save Project</literal>. You can now safely 
            exit ArgoUML without losing your work so far, or go on 
            creating your first diagram.</para>

          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>The Case Study (To be written)</title>

        <para>
          Here is where we are going to start the Case Study.
          It is at this point that you define your project;
          not your product, but your project.
          It can be argued that modeling concepts should apply here as well
          but this has not been well established.
          If you can take the time to look into the ArgoUML project, you will
          find that there are a large number of "lines of code" and lines of
          documentation that are part of the project, but not part of the
          product.
          For example, this document is part of the product while the Cookbook
          and the build.xml files are part of the project only.
          At a minimum the file structure of the project could be shown in a
          package diagram.
        </para>
        <para>
          ...
        </para>
      </sect1>

    </chapter>

    <chapter id="ch.tut.reqs">

      <title>Requirements Capture</title>

      <sect1>

        <title>Introduction</title>

        <indexterm>
        <primary>Requirement</primary><secondary>Capturing</secondary></indexterm>
        <para>Requirements capture is the process of identifying what 
        the <quote>customer</quote> wants from the proposed 
        system.</para>

        <para>The key at this stage is that we are in the problem 
        domain. At this stage we must describe everything from the 
        <quote>customer</quote> perspective and in the language of the 
        <quote>customer</quote>.</para>

        <para>The biggest risk we have in requirements capture is to 
        start thinking in terms of possible solutions. That must wait 
        until the <emphasis>Analysis Phase</emphasis> (see 
        <xref linkend="ch.tut.analysis"/>). One of the steps of the 
        Analysis Phase will be to take the output of the Requirements 
        Phase and recast it in the language of a deemed solution.</para>

        <para>Remember we are using both a 
        <emphasis>incremental</emphasis>, and an 
        <emphasis>iterative</emphasis> process.</para>

        <para>We may well come back to the requirements process again 
        as we break down the problem into smaller chunks, each of which 
        must have its requirements captured.</para>

        <para>We will certainly come back through the requirements 
        phase on each iteration as we seek to define the requirements 
        of more and more of the system</para>

        <note>

          <para>The only part of the requirements notation specified by 
          the UML standard is the use case diagram. The remainder is 
          process specific. The process described in this chapter draws 
          heavily on the Rational Unified Process.</para>

        </note>

      </sect1>

      <sect1>

        <title>The Requirements Capture Process</title>

        <indexterm><primary>Vision Document</primary></indexterm>
        <para>We start with a top-level view of the problem we are 
        solving and the key areas of functionality that we must address 
        in any solution. This is our <emphasis>vision 
        document</emphasis>, and should be just a few pages long.</para>

        <para>For example the top-level view of an automated teller 
        machine (ATM) might be that it should support the 
        following.</para>

        <orderedlist>

          <listitem>

            <para>Cash deposit, cash withdrawal and account inquiries 
            by customers.</para>

          </listitem>

          <listitem>

            <para>Maintenance of the equipment by the bank&apos;s 
            engineers, and unloading of deposits and loading of cash by 
            the local bank branch.</para>

          </listitem>

          <listitem>

            <para>Audit trail for all activities sent to the 
            bank&apos;s central computer.</para>

          </listitem>

        </orderedlist>

        <indexterm><primary>Actor</primary></indexterm>
        <para>From this top-level view we can extract the principal 
        activities of the system, and the external agents (people, 
        equipment) that are involved in those activities. These 
        activities are known as <emphasis>use cases</emphasis> and the 
        external agents are known as <emphasis>actors</emphasis>.</para>

        <para>Actors may be people or machines. From a practical 
        standpoint it is worth knowing the stakeholder behind any 
        machine, since only they will be able to engage with the 
        requirements capture process.</para>

        <indexterm><primary>Use Case</primary></indexterm>
        <para>Use cases should be significant activities for the 
        system. For example customer use of the ATM machine is a use 
        case. Entering a PIN number is not.</para>

        <para>There is a gray area between these two extremes. As we 
        shall see it is often useful to break very large use cases into 
        smaller sub-use cases. For example we may have sub-use cases 
        covering cash deposit, cash withdrawal and account 
        inquiry.</para>

        <para>There is no hard and fast rule. Some architects will 
        prefer a small number of relatively large use cases, others 
        will prefer a larger number of smaller use cases. A useful rule 
        of thumb is that any practical project ought to require no more 
        than about 30 use cases (if it needs more, it should be broken 
        into separate projects).</para>

        <para>We then show the relationship between use cases and 
        actors on one or more use case diagrams. For a large project 
        more than one diagram will be needed. Usually groups of related 
        use cases are shown on one diagram.</para>

        <para>We must then give a more detailed specification of each 
        use case. This covers its normal behavior, alternative 
        behaviors and any pre- and post-conditions. This is captured in 
        a document variously known as a <emphasis>use case 
        specification</emphasis> or <emphasis>use case 
        scenario</emphasis>.</para>

        <indexterm><primary>Supplementary Requirement 
        Specification</primary></indexterm>
        <para>Finally, since use cases are functional in nature, we 
        need a document to capture the non-functional requirements 
        (capacity, performance, environmental needs etc). These 
        requirements are captured in a document known as a 
        <emphasis>supplementary requirements 
        specification</emphasis>.</para>

        <sect2>

          <title>Process Steps</title>

          <para>The steps in the requirements capture process can be 
          summarized as follows.</para>

          <orderedlist>

            <listitem>

              <indexterm><primary>Vision Document</primary></indexterm>
              <para>Capture an overall view of the problem, and the 
              desired characteristics of its solution in the 
              <emphasis>vision document</emphasis>.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Use Case</primary></indexterm>
              <para>Identify the <emphasis>use case</emphasis> and 
              <emphasis>actors</emphasis> from the vision document and 
              show their relationships on one or more <emphasis>use 
              case diagrams</emphasis>.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Use Case 
              Specification</primary></indexterm>
              <indexterm><primary>Specification</primary><secondary>of 
              Use Case</secondary></indexterm>
              <para>Give detailed <emphasis>use case 
              specifications</emphasis> for each use case, covering 
              normal and alternate behavior, pre- and 
              post-conditions.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Non-functional 
              requirements</primary></indexterm>
              <indexterm><primary>Supplementary Requirement 
              Specification</primary></indexterm>
              <para>Capture all non-functional requirements in a 
              <emphasis>supplementary requirements 
              specification</emphasis>.</para>

            </listitem>

          </orderedlist>

          <para>In any iterative development process, we will 
          prioritize, and early iterations will focus on capturing the 
          key behavior of the most important use cases.</para>

          <para>Most modern requirements capture processes agree that 
          it is essential that the authoritative representative of the 
          customer is fully involved throughout the process.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.tut.req_process_output">

        <title>Output of the Requirements Capture Process</title>

        <para>Almost all the output of the requirements capture process 
        is documentary. The only diagram is the use case diagram, 
        showing the relationships between use cases and actors.</para>

        <sect2 id="s2.tut.vision_document">

          <title>Vision Document</title>

          <indexterm><primary>Vision Document</primary></indexterm>
          <para>Typical sections of this document would be as 
          follows.</para>

          <itemizedlist>

            <listitem>

              <para><emphasis>Summary</emphasis>. A statement of the 
              context, problem and solution goals.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Goals</primary><secondary>in the 
              Vision document</secondary></indexterm>
              <para><emphasis>Goals</emphasis>. What are we trying to 
              achieve (and how do we wish to achieve it).</para>

            </listitem>

            <listitem>

              <indexterm><primary>Market Context</primary><secondary>in 
              the Vision document</secondary></indexterm>
              <para><emphasis>Market Context</emphasis> or 
              <emphasis>Contractual Arrangements</emphasis>. For a 
              market led development, this should indicate target 
              markets, competitive differentiators, compelling events 
              and so forth. For a contractual development this should 
              explain the key contractual drivers.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Stakeholders</primary><secondary>in 
              the Vision document</secondary></indexterm>
              <para><emphasis>Stakeholders</emphasis>. The users (in 
              the widest sense) of the system. Many of these will map 
              in to actors, or control equipment that maps into 
              actors.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Key features</primary><secondary>in 
              the Vision document</secondary></indexterm>
              <para><emphasis>Key Features</emphasis>. At the very 
              highest level what are they key functional aspects of the 
              problem/desired solution. These will largely map down to 
              the use cases. It is helpful to give some prioritization 
              here.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Constraints</primary><secondary>in 
              the Vision document</secondary></indexterm>
              <indexterm><primary>Non-functional 
              parameters</primary><secondary>in the Vision 
              document</secondary></indexterm>
              <para><emphasis>Constraints</emphasis>. A high level view 
              of the non-functional parameters of the system. These 
              will be worked out in detail in the supplementary 
              requirements specification.</para>

            </listitem>

            <listitem>

              <para><emphasis>Appendix</emphasis>. A listing of the 
              actors and use cases that will be needed to meet this 
              vision. It is useful to link to these from the earlier 
              sections to ensure comprehensive coverage.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Use Case Diagram</title>

          <indexterm><primary>Use Case Diagram</primary></indexterm>
          <indexterm><primary>Diagram</primary><secondary>Use 
          Case</secondary></indexterm>
          <para>The vision document has identified the use cases and 
          actors. The use case diagram captures how they interact. In 
          our ATM example we have identified <quote>customer uses 
          machine</quote>, <quote>maintain machine</quote> and 
          <quote>audit</quote> as the three main use cases. We have 
          identified <quote>customer</quote>, maintenance 
          engineer<quote>,</quote><quote>local branch official</quote> 
          and <quote>central computer</quote> as the actors.</para>

          <para><xref linkend="fig.tut.atm_use_case_diagram_basic"/> 
          shows how this could be displayed on a use case diagram. The 
          use cases are shown as ovals, the actors as stick people 
          (even where they are machines), with lines (known as 
          <emphasis>associations</emphasis> connecting use cases to the 
          actors who are involved with them. A box around the use cases 
          emphasizes the boundary between the system (defined by the 
          use cases) and the actors who are external.</para>

          <note>

            <para>Not all analysts like to use a box around the use 
            cases. It is a matter of personal choice.</para>

          </note>

          <figure float="1" id="fig.tut.atm_use_case_diagram_basic">

            <title>Basic use case diagram for an ATM system</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/tutorial/atm_use_case_diagram_basic.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The following sections show how the basic use case 
          diagram can be extended to show additional information about 
          the system being designed.</para>

          <sect3>

            <title>Active and Passive Actors</title>

            <indexterm><primary>Active Actor</primary></indexterm>
            <para><emphasis>Active</emphasis> actors initiate 
            interaction with the system. This can be shown by placing 
            an arrow on the association from the actor pointing toward 
            the use case. In the ATM example, the customer is an active 
            actor.</para>

            <indexterm><primary>Passive Actor</primary></indexterm>
            <para>Interaction with <emphasis>passive</emphasis> actors 
            is initiated by the system. This can be shown by placing an 
            arrow on the association from the use case pointing toward 
            the actor. In the ATM example, the central computer is a 
            passive actor.</para>

            <para>This is a good example where the arrow helps, since 
            it allows us to distinguish an event driven system (the ATM 
            initiates interaction with the central computer) from a 
            polling system (the central computer interrogates the ATM 
            from time to time).</para>

            <para>Where an actor may be either active or passive, 
            depending on circumstances, the arrow may be omitted. In 
            the ATM example the bank engineer fits into this category. 
            Normally he is active, turning up on a regular cycle to 
            service the machine. However if the ATM detects a fault, it 
            may summon the engineer to fix it.</para>

            <para>
              The use of arrows on associations is referred to as 
              the <emphasis>navigation</emphasis> of the association.
              We shall see this used elsewhere in UML later on.
              The choice, by the OMG, of zero vice two arrowheads to show
              a bidirectional association is unfortunate.
              Under this convention you cannot distinguish between an
              association whose navigation has yet to be determined and one
              that is bidirectional.
            </para>

            <para>
            <xref linkend="fig.tut.atm_use_case_diagram_navigation"/> 
            shows the ATM use case diagram with navigation 
            displayed.</para>

            <figure float="1" id="fig.tut.atm_use_case_diagram_navigation">

              <title>Use case diagram for an ATM system showing 
              navigation.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/atm_use_case_diagram_navigation.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

          </sect3>

          <sect3>

            <title>Multiplicity</title>

            <indexterm><primary>Multiplicity</primary><secondary>in a 
            Use Case Diagram</secondary></indexterm>
            <para>It can be useful to show the 
            <emphasis>multiplicity</emphasis> of associations between 
            actors and use cases. By this we mean how many instances of 
            an actor interact with how many instances of the use 
            case.</para>

            <para>By default we assume one instance of an actor 
            interacts with one instance of a use case. In other cases 
            we can label the multiplicity of one end of the 
            association, either with a number to indicate how many 
            instances are involved, or with a range separated by two 
            periods (<literal>..</literal>). An asterisk (
            <literal>*</literal>) is used to indicate an arbitrary 
            number.</para>

            <para>In the ATM example, there is only one central 
            computer, but it may be auditing any number of ATM uses. So 
            we place the label <literal>0..*</literal> at the use case 
            end. There is no need for a label at the other end, since 
            the default is one.</para>

            <para>A local bank will have up to three officials 
            authorized to unload and load ATM machines. So at the actor 
            end of the relationship with the use case <literal>Maintain 
            ATM</literal>, we place the label <literal>1..3</literal>. 
            They may be dealing with any number of ATM machines, so at 
            the other end we place the label <literal>
            0..*</literal>.</para>

            <para>There may be any number of customers and there may be 
            any number of ATM systems they could use. So at each end of 
            the association we place the label <literal>
            0..*</literal>.</para>

            <para>
            <xref linkend="fig.tut.atm_use_case_diagram_multiplicity"/> 
            shows the ATM use case diagram with multiplicity 
            displayed.</para>

            <figure float="1" id="fig.tut.atm_use_case_diagram_multiplicity">

              <title>Use case diagram for an ATM system showing 
              multiplicity.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/atm_use_case_diagram_multiplicity.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>Multiplicity can clutter a diagram, and is often not 
            shown, except where it is critical to understanding. In the 
            ATM example we would only choose to show <literal>
            1..3</literal> against the local bank official, since all 
            others are obvious from the context.</para>

          </sect3>

          <sect3>

            <title>Hierarchies of Use Cases</title>

            <indexterm><primary>Hierarchy of Use 
            Cases</primary></indexterm>
            <indexterm><primary>Use 
            Case</primary><secondary>Hierarchy</secondary></indexterm>
            <para>In our ATM example so far we have just three use 
            cases to describe all the behavior of the system. While use 
            cases should always describe a significant chunk of system 
            behavior, if they are too general they can be difficult to 
            describe.</para>

            <para>We could for example define the behavior of the use 
            case <quote>Use ATM</quote> in terms of the behavior of 
            three simpler use cases, <quote>Deposit Cash</quote>, 
            <quote>Withdraw Cash</quote> and <quote>Query 
            Account</quote>. The main use case could be specified by 
            <emphasis>including</emphasis> the behavior of the 
            subsidiary use cases where needed.</para>

            <para>Similarly the <quote>Maintain ATM</quote> use case 
            could be defined in terms of two use cases <quote>Maintain 
            Equipment</quote> and <quote>Reload ATM</quote>. In this 
            case the two actors involved in the main use case are 
            really only involved in one or other of the two subsidiary 
            use cases and this can be shown on the diagram.</para>

            <indexterm><primary>Include 
            Relationship</primary></indexterm>
            <indexterm>
            <primary>Relationship</primary><secondary>Include</secondary></indexterm>
            <para>The decomposition of a use case into simpler sub-use 
            cases is shown in UML by using an <emphasis>include 
            relationship</emphasis>, a dotted arrow from the main use 
            case to the subsidiary, with the label 
            <emphasis>&laquo;include&raquo;</emphasis>.</para>

            <figure float="1" id="fig.tut.atm_use_case_diagram_include">

              <title>Use case diagram for an ATM system showing include 
              relationships.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/atm_use_case_diagram_include.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>Include relationships are fine for breaking down the 
            use case behaviors in to hierarchies. However we may also 
            want to show a use case that is an 
            <emphasis>extension</emphasis> to an existing use case to 
            cater for a particular circumstance.</para>

            <para>In the ATM example we have a use case covering 
            routine maintenance of the ATM, <quote>Maintain 
            Equipment</quote>. We also want to cover the special case 
            of an unscheduled repair caused by the ATM detecting an 
            internal fault.</para>

            <indexterm><primary>Extend 
            Relationship</primary></indexterm>
            <indexterm>
            <primary>Relationship</primary><secondary>Extend</secondary></indexterm>
            <para>This is shown in UML by the 
            <emphasis>extend</emphasis> relationship. In the main use 
            case, we specify a name for a location in the description, 
            where an extension to the behavior could be attached. The 
            name and location are shown in a separate compartment 
            within the use case oval. The representation extend 
            relationship is the same as the include relationship, but 
            with the label <emphasis>&laquo;extend&raquo;</emphasis>. Alongside the 
            extend relationship, we specify the condition under which 
            that behavior will be attached.</para>

            <para><xref linkend="fig.tut.atm_use_case_diagram_extend"/> 
            shows the ATM use case diagram with an extend relationship 
            to a use case for unscheduled repairs. The diagram is now 
            getting rather complex, and so we have split it into two, 
            one for the maintenance side of things, the other for 
            customer usage and audit.</para>

            <para>The <quote>Maintain Equipment</quote> use case 
            defines a name <quote>Unsched</quote>, at the start of its 
            description. The extending use case <quote>Unscheduled 
            Repair</quote> is attached there when the ATM detects an 
            internal error.</para>

            <figure float="1" id="fig.tut.atm_use_case_diagram_extend">

              <title>Use case diagram for an ATM system showing an 
              extend relationship.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/tutorial/atm_use_case_diagram_extend.gif"
               format="GIF"/></imageobject></mediaobject></screenshot>
            </figure>

            <indexterm><primary>Use Case 
            Generalization</primary></indexterm>
            <indexterm><primary>Use Case 
            Specialization</primary></indexterm>
            <indexterm><primary>Generalize a Use 
            Case</primary></indexterm>
            <indexterm><primary>Specializations</primary><secondary>of 
            Use Case</secondary></indexterm>
            <para>
              Use cases may be linked together in one other way. 
              One use case may be a <emphasis>generalization</emphasis>
              of a subsidiary use case (or alternatively the subsidiary 
              is a <emphasis>specialization</emphasis> of the main use 
              case).
              This is very like the extends relationship, but 
              without the constraint of specific extension points at 
              which the main use case may be extended, and with no 
              condition on when the subsidiary use case may be 
              used.</para>

            <para>
              Generalization is shown on a use case diagram by an 
              arrow with solid line and solid white head from the 
              subsidiary to the main use case.
              This may be useful when a subsidiary use case 
              specializes the behavior of the main use case at a large 
              number of positions and under a wide range of 
              circumstances.
              However the lack of any restriction makes 
              generalization very hard to specify precisely.
              In general use an extend relationship instead.
            </para>

          </sect3>

        </sect2>

        <sect2>

          <title>The Use Case Specification</title>

          <indexterm><primary>Use Case 
          Specification</primary></indexterm>
          <indexterm><primary>Specification</primary><secondary>of Use 
          Case</secondary></indexterm>
          <indexterm><primary>Use Case Scenario</primary></indexterm>
          <para>
            Each use case must be documented to explain in detail 
            the behavior it is specifying.
            ArgoUML assists in this area through the generation of graphic
            files for inclusion in this documentation.
            This document is known by different names in different processes:
            <emphasis>use case specification</emphasis>,
            <emphasis>use case scenario</emphasis> or even (confusingly) just
            <emphasis>use case</emphasis>.
          </para>

          <para>A typical use case specification will include the following 
          sections.</para>

          <itemizedlist>

            <listitem>

              <indexterm><primary>Name</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use Case Name</primary></indexterm>
              <para><emphasis>Name</emphasis>. The name of the use case 
              to which this relates.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Goal</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use Case Goal</primary></indexterm>
              <para><emphasis>Goal</emphasis>. A one or two line 
              summary of what this use case achieves <emphasis>for its 
              actors</emphasis>.</para>

            </listitem>

            <listitem>

              <para><emphasis>Actors</emphasis>. The actors involved in 
              this use case, and any context regarding their 
              involvement.</para>

              <note>

                <para>This should not be a description of the actor. 
                That should be associated with the actor on the use 
                case diagram.</para>

              </note>

            </listitem>

            <listitem>

              <indexterm><primary>Pre-condition</primary><secondary>of 
              Use Case</secondary></indexterm>
              <indexterm>
              <primary>Pre-assumptions</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use Case 
              Pre-condition</primary></indexterm>
              <para><emphasis>Pre-condition</emphasis>. These would be 
              better named <quote>pre-assumptions</quote>, but the term 
              used everywhere is pre-conditions. This is a statement of 
              any simplifying assumptions we can make at the start of 
              the use case.</para>

              <para>In the ATM example we might make the assumption for 
              the<quote>Maintain Equipment</quote> use case that an 
              engineer is always available, and we do not need to worry 
              about the case where a routine maintenance visit is 
              missed.</para>

              <caution>

                <para>Avoid pre-conditions wherever possible. You need 
                to be absolutely certain that the pre-condition holds 
                under all possible circumstances. If not your system 
                will be under specified and hence will fail when the 
                pre-condition is not true. Alternatively, when you 
                cannot be certain the pre-condition is always true, you 
                will need to specify a second use case to handle the 
                pre-condition being false. In the first case, 
                pre-conditions are a source of problems, in the second 
                a source of more work.</para>

              </caution>

            </listitem>

            <listitem>

              <indexterm><primary>Basic Flow</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use Case</primary><secondary>Basic 
              Flow</secondary></indexterm>
              <indexterm><primary>Scenario</primary></indexterm>
              <para><emphasis>Basic Flow</emphasis>. The linear 
              sequence of steps that describe the behavior of the use 
              case in the <quote>normal</quote> scenario. Where a use 
              case has a number of scenarios that could be normal, one 
              is arbitrarily selected. Specifying the basic flow is 
              described in more detail in 
              <xref linkend="s3.tut.basic_flow"/> below.</para>

            </listitem>

            <listitem>

              <indexterm><primary>Alternate 
              Flows</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use 
              Case</primary><secondary>Alternate 
              Flows</secondary></indexterm>
              <para><emphasis>Alternate Flows</emphasis>. A series of 
              linear sequences describing each of the alternative 
              behaviors to the basic flow. Specifying alternate flows 
              is described in more detail in 
              <xref linkend="s3.tut.alternate_flows"/>.</para>

            </listitem>

            <listitem>

              <indexterm>
              <primary>Post-conditions</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm>
              <primary>Post-assumptions</primary><secondary>of Use 
              Case</secondary></indexterm>
              <indexterm><primary>Use Case 
              Post-conditions</primary></indexterm>
              <para><emphasis>Post-conditions</emphasis>. These would 
              be better named <quote>post-assumptions</quote>. This is 
              a statement of any assumptions that we can make at the 
              end of the use case. Most useful where the use case is 
              one of a series of subsidiary use cases that are included 
              in a main use case, where they can form the 
              pre-conditions of the next use case to be included.</para>

              <caution>

                <para>Like pre-conditions, post-conditions are best 
                avoided. They place a burden on the specification of 
                the use case flows, to ensure that the post-condition 
                always holds. They therefore are also a source of 
                problems and extra work.</para>

              </caution>

            </listitem>

            <listitem>

              <para><emphasis>Requirements</emphasis>. In an ideal 
              world the vision document, use case diagrams, use case 
              specifications and supplementary requirements 
              specification would form the requirements for a 
              project.</para>

              <para>For most market-led developments, where ownership 
              of requirements is within the same business as the team 
              who will do the development, this is now usually the 
              case. The marketing department can learn use case based 
              requirements capture and analysis to link to their 
              customer facing activities.</para>

              <para>However for external contract developments, 
              customers may insist on a traditional <quote>list of 
              features</quote> as the basis of the contract. Where this 
              is the case, this section of the use case specification 
              should link to the contract features that are covered by 
              the use case.</para>

              <para>This is often done through a third party tool that 
              can link documents, providing automated checking of 
              coverage, in which case this section is not needed, or 
              may be generated automatically.</para>

            </listitem>

          </itemizedlist>

          <para>The final size of the use case specification will 
          depend on the complexity of the use case. As a rule of thumb, 
          most use cases take around 10-15 pages to specify, the bulk 
          of which is alternate flows. If you are much larger than 
          this, consider breaking the use case down. If you are much 
          smaller consider whether the use case is addressing too small 
          a chunk of behavior.</para>

          <sect3 id="s3.tut.basic_flow">

            <title>Specifying the Basic Flow</title>

            <indexterm><primary>Basic Flow</primary><secondary>of Use 
            Case</secondary></indexterm>
            <indexterm><primary>Use Case</primary><secondary>Basic 
            Flow</secondary></indexterm>
            <para>All flows in a use case specification are linear&mdash;that 
            is there is no conditional branching. Any choices in flows 
            are handled by specifying another alternate flow that takes 
            over at the choice point. It is important to remember we 
            are specifying behavior here, not programming it.</para>

            <para>A flow is specified as a series of numbered steps. 
            Each step must involve some interaction with an actor, or 
            at least generate a change that is observable externally by 
            an actor. Requirements capture should not be specifying 
            hidden internal behavior of a system.</para>

            <para>For example we might give the following sequence of 
            steps for the basic flow of the use case &quot;Withdraw 
            Cash&quot; in our ATM example.</para>

            <orderedlist>

              <listitem>

                <para>Customer indicates a receipt is required.</para>

              </listitem>

              <listitem>

                <para>Customer enters amount of cash required.</para>

              </listitem>

              <listitem>

                <para>ATM verifies with the central computer that the 
                customer can make this withdrawal.</para>

              </listitem>

              <listitem>

                <para>ATM dispenses cash to the customer.</para>

              </listitem>

              <listitem>

                <para>ATM issues receipt to customer.</para>

              </listitem>

            </orderedlist>

            <para>Remember this is a sub-use case included in the main 
            <quote>Use ATM</quote> use case, which will presumably 
            handle checking of cards and PINs before invoking this 
            included use case.</para>

            <note>

              <para>The first step is not a condition. We take as our 
              basic flow the case where the customer does want a 
              receipt. The case where the customer does not want a 
              receipt will be an alternative flow.</para>

            </note>

          </sect3>

          <sect3 id="s3.tut.alternate_flows">

            <title>Specifying the Alternate Flows</title>

            <indexterm><primary>Alternate Flows</primary><secondary>of 
            Use Case</secondary></indexterm>
            <indexterm><primary>Use Case</primary><secondary>Alternate 
            Flows</secondary></indexterm>
            <indexterm><primary>Alternative 
            scenarios</primary></indexterm>
            <para>This captures the alternative scenarios, as linear 
            flows, by reference to the basic flow. Initially we just 
            build a list of the alternate flows.</para>

            <orderedlist inheritnum="inherit" numeration="upperalpha">

              <listitem>

                <orderedlist inheritnum="inherit" numeration="arabic">

                  <listitem>

                    <para>Customer does not require a receipt.</para>

                  </listitem>

                  <listitem>

                    <para>Customer&apos;s account will not support the 
                    withdrawal.</para>

                  </listitem>

                  <listitem>

                    <para>Communication to the central computer is 
                    down.</para>

                  </listitem>

                  <listitem>

                    <para>The customer cancels the transaction.</para>

                  </listitem>

                  <listitem>

                    <para>The customer fails to take the dispensed 
                    cash.</para>

                  </listitem>

                </orderedlist>

              </listitem>

            </orderedlist>

            <para>Subsequently we flesh out each alternate flow, by 
            reference to the basic flow. For example the first 
            alternate flow might look like.</para>

            <orderedlist inheritnum="inherit" numeration="upperalpha">

              <listitem>

                <orderedlist inheritnum="inherit" numeration="arabic">

                  <listitem>

                    <para>Customer does not require a receipt.</para>

                    <orderedlist inheritnum="inherit" numeration="arabic">

                      <listitem>

                        <para>At step 1 of the basic flow the customer 
                        indicates they do not want a receipt.</para>

                      </listitem>

                      <listitem>

                        <para>The basic flow proceeds from step 2 to 
                        step 4, and step 5 is not used.</para>

                      </listitem>

                    </orderedlist>

                  </listitem>

                </orderedlist>

              </listitem>

            </orderedlist>

            <para>The convention is to number the various alternate 
            flows as A.1, A.2, A.3, etc. The steps within an alternate 
            flow are then numbered from this. So the steps of the first 
            alternate flow would be A.1.1, A.1.2, A.1.3, etc.</para>

          </sect3>

          <sect3>

            <title>Iterative Development of Use Case 
            Specifications</title>

            <para>Iterative development will prioritize the use cases, 
            and the first iterations will address the most 
            important.</para>

            <para>Early iterations will capture the basic flows of the 
            most important use cases with only essential detail and 
            list the headings of the main alternate flows.</para>

            <para>Later iterations will address the remaining use 
            cases, flesh out the steps on individual alternate flows 
            and possibly provide more detail on individual steps.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Supplementary Requirement Specification</title>

          <indexterm><primary>Supplementary Requirement 
          Specification</primary></indexterm>
          <indexterm><primary>Non-functional 
          requirements</primary></indexterm>
          <indexterm><primary>Non-functional 
          constraints</primary></indexterm>
          <para>This captures the non-functional requirements or 
          constraints placed on the system. Since use cases are 
          inherently functional in nature, they cannot capture this 
          sort of information.</para>

          <note>

            <para>Some analysts like to place non-functional 
            requirements in a section at the end of each use case 
            specification, containing the non-functional requirements 
            relevant to the use case.</para>

            <para>
              This can cause some problems.
              First key non-functional requirements (for example about
              performance) may need to appear in many use cases and it is bad
              practice to replicate information.
              Secondly there are invariably some non-functional requirements
              that are system wide and need a system wide document.
              Hence my preference for a single supplementary requirements
              specification.
            </para>

          </note>

          <para>There should be a section for each of the main areas of 
          non-functional requirements. The checklist provided by Ian 
          Sommerville in his book <emphasis>Software 
          Engineering</emphasis> (Third Edn, Addison-Wesley, 1989) is a 
          useful guide.</para>

          <itemizedlist>

            <listitem>

              <para><emphasis>Speed</emphasis>. Processor performance, 
              user/event response times, screen refresh time.</para>

            </listitem>

            <listitem>

              <para><emphasis>Size</emphasis>. Main memory (and 
              possibly caches), disc capacity.</para>

            </listitem>

            <listitem>

              <para><emphasis>Ease of use</emphasis>. Training time, 
              style and detail of help system.</para>

            </listitem>

            <listitem>

              <para><emphasis>Reliability</emphasis>. Mean time to 
              failure, probability of unavailability, rate of failure, 
              availability.</para>

            </listitem>

            <listitem>

              <para><emphasis>Robustness</emphasis>. Time to restart 
              after failure, percentage of events causing failure, 
              probability of data corruption on failure.</para>

            </listitem>

            <listitem>

              <para><emphasis>Portability</emphasis>. Percentage of 
              target-dependent code/classes, number of target 
              systems.</para>

            </listitem>

          </itemizedlist>

          <para>To this we should add sections on environment 
          (temperature, humidity, lightening protection status) and 
          standards compliance.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.argo_use_cases">

        <title>Using Use Cases in ArgoUML</title>

        <para>ArgoUML allows you to draw use case diagrams. When you 
        create a new project it has a use case diagram created by 
        default, named <literal>use case diagram 1</literal>. Select 
        this by button&nbsp;1 click on the diagram name in the explorer (the 
        upper left quadrant of the user screen).</para>

        <para>New use case diagrams can be created as needed through 
        <literal>Create Diagram</literal> on the main menu bar or on 
        the Create Diagram Toolbar. They are edited in the editing pane 
        (the upper right quadrant of the user screen).</para>

        <sect2>

          <title>Actors</title>

          <indexterm><primary>Create 
          New</primary><secondary>Actor</secondary></indexterm>
          <indexterm><primary>Actor</primary></indexterm>
          <para>To add an actor to the diagram use button&nbsp;1 click on 
          the actor icon on the editing pane toolbar (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/actor.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          and then button&nbsp;1 click at the location where you wish to 
          place it. The actor can be moved subsequently by button&nbsp;1 
          motion (i.e. button&nbsp;1 down over the actor to select it, move 
          to the new position and button&nbsp;1 release to drop the actor in 
          place.</para>

          <para>Multiple actors can be added in one go, by using 
          button&nbsp;1 double click on the actor icon. Each subsequent 
          button&nbsp;1 click will drop an actor on the diagram. A button&nbsp;1 
          click on the select icon (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/select.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          will stop adding actors.</para>

          <para>The actors name is set in its property panel. First 
          select the actor (if not already selected) on the editing 
          pane using button&nbsp;1 click. Then click on the <literal>
          Properties</literal> tab in the details pane. The name is 
          entered in the name field, and will appear on the 
          screen.</para>

          <para>As a shortcut, double button&nbsp;1 click on the name of the 
          actor in the editing pane (or just typing on the keyboard 
          when an actor is selected) will allow the name to be edited 
          directly. This is a convenient way to enter a name for a new 
          actor.</para>

          <para>Having created the actor, you will see it appear in the 
          explorer (the upper left quadrant of the user screen). This 
          shows all the model elements created within the UML design. A drop 
          down at the top of the explorer controls the ordering of 
          model elements in the explorer. The most useful are the <literal>
          Package-centric</literal> (default) and <literal>
          Diagram-centric</literal>. The latter shows model elements grouped 
          by the diagram on which they appear.</para>

        </sect2>

        <sect2>

          <title>Use Cases</title>

          <indexterm><primary>Create New</primary><secondary>Use 
          Case</secondary></indexterm>
          <indexterm><primary>Use Case</primary></indexterm>
          <para>The procedure for adding use cases is the same as that 
          for adding actors, but using the use case icon on the editing 
          pane toolbar (<guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/use_case.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>).</para>

          <para>By default use cases in ArgoUML do not display their 
          extension points (for use in extend relationships). You can 
          show the extension point compartment in one of two 
          ways.</para>

          <orderedlist>

            <listitem>

              <para>Select the use case in the editing pane with 
              button&nbsp;1 click, then select the <literal>Style</literal> 
              tab in the details pane and button&nbsp;1 click on the 
              <literal>Display: Extension Points</literal> check 
              box.</para>

            </listitem>

            <listitem>

              <para>Use button&nbsp;2 click over the use case in the editing 
              pane to display a context-sensitive pop-up menu and from 
              that choose <literal>Show/Show Extension Point 
              Compartment</literal>.</para>

            </listitem>

          </orderedlist>

          <para>The same approaches can be used to hide the extension 
          point compartment.</para>

          <sect3>

            <title>Adding an Extension Point to a Use Case</title>

            <indexterm><primary>Create 
            New</primary><secondary>Extension 
            Point</secondary></indexterm>
            <indexterm><primary>Extension Point</primary></indexterm>
            <para>There are two ways to add an extension point to a use 
            case.</para>

            <orderedlist>

              <listitem>

                <para>Select the use case on the editing pane with 
                button&nbsp;1 click. Then click on the <literal>Add 
                Extension Point</literal> icon (
                <guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/extension_point.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
                on the toolbar, and a new extension point with default 
                name and location will be added after any existing 
                extension points.</para>

                <note>

                  <para>The <literal>Add Extension Point</literal> icon 
                  is grayed out and unusable until a use case is 
                  selected.</para>

                </note>

              </listitem>

              <listitem>

                <para>Select the use case on the editing pane with 
                button&nbsp;1 click and then select its property tab in the 
                details pane. A button&nbsp;2 click over the <literal>
                Extension Points:</literal> field will bring up a 
                context-sensitive pop-up menu. Select <literal>
                Add</literal> to add a new extension point.</para>

                <para>If any extension points already exist, they will 
                be shown in this field on the property tab. The new 
                extension point will be inserted immediately before the 
                entry over which the pop-up menu was invoked. This 
                ordering can be changed later by using the <literal>
                Move Up</literal> and <literal>Move Down</literal> 
                entries on the pop-up menu.</para>

              </listitem>

            </orderedlist>

            <para>Whichever method is used, the new extension point is 
            selected, and its property tab can be displayed in the 
            details pane. The name and location of the extension point 
            are free text, set in the corresponding fields of the 
            property tab.</para>

            <para>An existing extension point can be edited from its 
            property tab. The property tab can be reached in two 
            ways.</para>

            <orderedlist>

              <listitem>

                <para>If the extension point compartment for the use 
                case is displayed on the diagram, select the use case 
                with button&nbsp;1 click and then select the extension point 
                with a further button&nbsp;1 click. The property tab can 
                then be selected in the details pane.</para>

              </listitem>

              <listitem>

                <para>Otherwise select the use case and its property 
                tab in the details pane. A button&nbsp;1 click on the 
                desired entry in the <literal>Extension 
                Points</literal> field will bring up the property tab 
                for the extension point in the details pane.</para>

              </listitem>

            </orderedlist>

            <para>The name and location fields of the extension point 
            may then be edited.</para>

            <para>As a shortcut, where the extension point compartment 
            is displayed, double click on the extension point allows 
            text to be typed in directly. This is parsed to set name 
            and location for the extension point.</para>

            <para>Extension points may be deleted, or their ordering 
            changed by using the button&nbsp;2 pop-up menu over the <literal>
            Extension Points</literal> field in the use case property 
            tab.</para>

            <para>Having created an extension point, it will appear in 
            the explorer (upper left quadrant of the user screen). 
            Extension points are always shown in a sub-tree beneath 
            their owning use case.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Associations</title>

          <indexterm><primary>Create 
          New</primary><secondary>Association in a Use Case 
          Diagram</secondary></indexterm>
          <indexterm><primary>Association</primary><secondary>in a Use 
          Case Diagram</secondary></indexterm>
          <para>To join a use case to an actor on the diagram use 
          button&nbsp;1 click on the association icon on the editing pane 
          toolbar (<guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/association.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>). 
          Hold button&nbsp;1 down at the use case, move to the actor and 
          release button&nbsp;1 (or alternatively start at the actor and 
          finish at the use case).</para>

          <para>This will create a straight line between actor and use 
          case. You can segment the line by holding down button&nbsp;1 down 
          on the line and moving before releasing. A vertex will be 
          added to the line, which you can move by button&nbsp;1 motion. A 
          vertex can be removed by picking it up and sliding to one end 
          of the line.</para>

          <para>Multiple associations can be added in one go, by using 
          button&nbsp;1 double click on the association icon. Each 
          subsequent button&nbsp;1 down/motion/release sequence will join an 
          actor to a use case. Use button&nbsp;1 on the select icon (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/select.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          to stop adding associations.</para>

          <para>It is also possible to add associations using small 
          <quote>handles</quote> that appear to the left and right of a 
          use case or actor when it is selected and the mouse is over 
          it. Dragging the handle from a use case to an actor will 
          create an association to that actor (and similarly by 
          dragging a handle from an actor to a use case).</para>

          <para>Dragging a handle from a use case into empty space will 
          create a new actor to go on the other end. Similarly dragging 
          a handle from an actor into empty space will create a new use 
          case.</para>

          <para>It is possible to give an association a name, 
          describing the relationship of the actor to the use case, 
          although this is not usually necessary. This is done through 
          the property tab of the association. Such a name appears 
          alongside the association near its center.</para>

          <sect3 id="s3.tut.req_argo_navigation">

            <title>Setting Navigation</title>

            <indexterm><primary>Setting 
            Navigation</primary><secondary>to an association in a Use 
            Case Diagram</secondary></indexterm>
            <indexterm>
            <primary>Navigation</primary><secondary>Setting</secondary></indexterm>
            <para>There are two ways of setting the navigation of an 
            association.</para>

            <orderedlist>

              <listitem>

                <para>Use button&nbsp;2 click on the association to bring up 
                a context-sensitive pop-up menu. The <literal>
                Navigability</literal> sub-menu has options for 
                bi-directional navigation (the default, with no arrows) 
                and for navigability Actor-&gt;Use Case and
                Use Case-&gt;Actor.</para>

              </listitem>

              <listitem>

                <para>Use button&nbsp;1 to select the association and select 
                its property tab in the details pane. This shows a 
                field named <literal>Association Ends:</literal>, with 
                entries for each end labeled by the actor or use case 
                name and its multiplicity. Select the end that should 
                be at the tail of the arrow with button&nbsp;1 click. This 
                brings up the property tab for the association end. Use 
                button&nbsp;1 click to uncheck the <literal>
                Navigability</literal> box.</para>

                <note>

                  <para>This may seem counter-intuitive, but in fact 
                  associations by default are navigable in both 
                  directions (when no arrows are shown). This process 
                  is <emphasis>turning off</emphasis> navigation at one 
                  end, rather than turning it on at the other.</para>

                </note>

              </listitem>

            </orderedlist>

            <para>You will see it is possible to give an association 
            end a name in its property tab. This name will appear at 
            that end of the association, and can be used to indicate 
            the <emphasis>role</emphasis> being played by an actor or 
            use case in an association.</para>

            <para>For example a time management system for a business 
            may have use cases for completing time sheets and for 
            signing off time sheets. An employee actor may be involved 
            in both, one as an employee, but the other in a role as 
            manager.</para>

          </sect3>

          <sect3>

            <title>Setting Multiplicity</title>

            <indexterm><primary>Setting 
            Multiplicity</primary><secondary>to an association in a Use 
            Case Diagram</secondary></indexterm>
            <indexterm>
            <primary>Multiplicity</primary><secondary>Setting</secondary></indexterm>
            <para>There are two ways of setting multiplicity at the end 
            of an association.</para>

            <orderedlist>

              <listitem>

                <para>Button&nbsp;2 click over the end of an association 
                will cause a context-sensitive pop-up menu to appear 
                with a sub-menu labeled <literal>
                Multiplicity</literal>. This allows you to select from 
                <literal>1</literal> (the default), <literal>
                0..1</literal>, <literal>0..*</literal> and <literal>
                1..*</literal>.</para>

              </listitem>

              <listitem>

                <para>Bring up the property sheet for the association 
                end as described for setting navigation (see the second 
                option in <xref linkend="s3.tut.req_argo_navigation"/>
                ). A drop down menu gives a range of multiplicity 
                options that may be selected.</para>

              </listitem>

            </orderedlist>

            <para>The second of these two approaches has a wider range 
            of options, although ArgoUML does not currently allow the 
            user to set an arbitrary multiplicity.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Hierarchical Use Cases</title>

          <indexterm><primary>Hierarchical Use 
          Cases</primary></indexterm>
          <indexterm><primary>Use Case, 
          Hierarchical</primary></indexterm>

          <para>
            UML as originally designed allowed use cases to be organized by
            grouping them in packages as well as by specifying relations among
            them.
            In ArgoUML only the relations mechanism is supported.
            All Three of the relations that apply to use cases are supported.
            These are <emphasis>include</emphasis>, <emphasis>extend</emphasis>
            and <emphasis>generalization</emphasis>.
          </para>

          <sect3>

            <title>Includes</title>

            <indexterm><primary>Create New</primary><secondary>Include 
            Relationship in a Use Case Diagram</secondary></indexterm>
            <indexterm><primary>Include 
            Relationship</primary><secondary>in a Use Case 
            Diagram</secondary></indexterm>
            <indexterm>
            <primary>Relationship</primary><secondary>Include</secondary></indexterm>
            <para>The procedure for adding an include relationship is 
            the same as that for adding an association, but using the 
            include icon from the editing pane toolbar (
            <guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/include.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
            to join two use cases.</para>

            <para>Since include relationships are directional the order 
            in which the two ends are selected is important. The 
            <emphasis>including</emphasis> (main) use case should be 
            selected first (button&nbsp;1 down) and the 
            <emphasis>included</emphasis> (subsidiary) use case second 
            (button&nbsp;1 release).</para>

            <para>It is possible to name include relationships using 
            the property tab, but this is rarely done, and will not be 
            displayed on the use case diagram.</para>

          </sect3>

          <sect3>

            <title>Extends</title>

            <indexterm><primary>Create New</primary><secondary>Extend 
            Relationship in a Use Case Diagram</secondary></indexterm>
            <indexterm><primary>Extend 
            Relationship</primary><secondary>in a Use Case 
            Diagram</secondary></indexterm>
            <indexterm>
            <primary>Relationship</primary><secondary>Extend</secondary></indexterm>
            <para>The procedure for adding an extend relationship is 
            the same as that for adding an include relationship, but 
            using the extend icon from the editing pane toolbar (
            <guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/extend.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
            to join two use cases.</para>

            <para>As with include relationships, the order of selection 
            matters. In this case, the <emphasis>extending</emphasis> 
            (subsidiary) use case should be selected first (button&nbsp;1 
            down) and the <emphasis>extending</emphasis> (main) use 
            case second (button&nbsp;1 release).</para>

            <note>

              <para>This is the reverse of the include relationship, 
              but reflects the way that designer&apos;s tend to think. 
              The fact that the extend icon&apos;s arrow points upward 
              (the opposite of the include icon) should help remind you 
              of this.</para>

            </note>

            <para>To set a condition for the extend relationship, 
            select the extend relationship in the editing pane 
            (button&nbsp;1 click) and then bring up its property tab in the 
            details pane ((button&nbsp;1 click on the tab). The text of the 
            condition may be typed in the <literal>Condition</literal> 
            field. Long conditions may be split over several lines if 
            desired. The condition is displayed under the <literal>
            &laquo;extend&raquo;</literal> label on the diagram.</para>

            <para>It is possible to name extend relationships using the 
            property tab, but this is rarely done, and will not be 
            displayed on the use case diagram.</para>

          </sect3>

          <sect3>

            <title>Generalization</title>

            <indexterm><primary>Create 
            New</primary><secondary>Generalization relationship in a 
            Use Case Diagram</secondary></indexterm>
            <indexterm><primary>Generalization 
            Relationship</primary><secondary>in a Use Case 
            Diagram</secondary></indexterm>
            <indexterm>
            <primary>Relationship</primary><secondary>Generalization</secondary></indexterm>
            <para>The procedure for adding generalizations, is the same 
            as for adding extend relationships, but using the 
            generalization icon from the editing pane toolbar (
            <guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/generalization.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon>).</para>

            <para>Since generalization is a directed relationship, the 
            order of selection matters. The specialized use case should 
            be selected first (button&nbsp;1 down) and the generalized 
            second (button&nbsp;1 release).</para>

            <para>It is also possible to add generalizations using 
            small <quote>handles</quote> that appear to the top and 
            bottom of a use case when it is selected. Dragging the 
            handle at the top to another use case will create a 
            generalization. The original use case is the specializing 
            end, and the use case to which the handle was dragged will 
            be the generalizing end. Dragging into empty space will 
            create a new use case to be the generalizing end.</para>

            <para>Similarly dragging on the bottom handle will create a 
            generalization in which the original use case is the 
            <emphasis>generalizing</emphasis> end.</para>

            <para>Generalization is also permitted between actors, 
            although its use is beyond the scope of this tutorial. 
            Unlike use cases there are no generalization handles on 
            actors, so generalizations must be created using the 
            toolbar icon.</para>

            <para>It is possible to name generalization relationships 
            using the property tab, but this is rarely done. If a name 
            is provided, it will be displayed on the use case 
            diagram.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Stereotypes</title>

          <indexterm><primary>Stereotype</primary><secondary>in Use 
          Case Diagrams</secondary></indexterm>
          <para>
            UML has the concept of <emphasis>stereotyping</emphasis> as a way
            of extending the basic notation.
            It may prove useful for example to model a problem at both the
            business level and the engineering level. 
            It is for this reason that the OMG distinguishes between a PIM
            and a PSM.
            For both of these we will need use cases, but the use cases 
            at the business level hold a different sort of information to 
            those at the engineering level.
            Very likely they use different language and notation in their
            underlying use case specifications.
          </para>

          <para><emphasis>Stereotypes</emphasis> are used to label UML 
          model elements such as use cases, to indicate that they belong to 
          a certain category. Such labels are shown in guillemots (
          <literal>&laquo;&nbsp;&raquo;</literal>) above the name of the model element on the 
          diagram. The UML standard defines a number of standard 
          stereotypes, and the user may define more stereotypes of his 
          own.</para>

          <para>You will see that ArgoUML has a drop down selector, 
          <literal>Stereotype</literal> on every property tab. This is 
          populated with the standard stereotypes, to which you may add 
          your own user defined ones.</para>

          <para>The details of stereotyping are beyond the scope of 
          this tutorial. The reference manual (see 
          <xref linkend="s1.ref.stereotype"/>) documents the support 
          provided in ArgoUML.</para>

          <warning>

            <para>ArgoUML is missing a few of the standard UML 
            stereotypes. In addition not all model elements will actually 
            display the stereotype on the diagram. At present this 
            includes use cases and actors.</para>

          </warning>

        </sect2>

        <sect2>

          <title>Documentation</title>

          <indexterm><primary>Documentation in Use Case 
          Diagrams</primary></indexterm>
          <para>ArgoUML has some simple documentation facilities 
          associated with model elements on a diagram. In general these 
          should be used only to record the location of material in 
          documents that can be handled by a mainstream editor or word 
          processor, not the actual documentation itself.</para>

          <para>Documentation for a particular model element is recorded 
          through the documentation tab in the details pane (the 
          quadrant of the user screen at the bottom right).</para>

          <para>In addition annotation may be added to diagrams using 
          the text icon on the editing pane toolbar (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/text.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>).</para>

          <para>The recommendation is that a use case diagram should 
          use the documentation tab of actors to record information 
          about the actor, or if the actor is complex to refer to a 
          separate document that holds information about the 
          actor.</para>

          <para>The documentation tab of use cases should record the 
          location of the use case specification. The information in a 
          use case specification (for all but the simplest use cases) 
          is too complex to be placed directly in the tab.</para>

          <para>The project should also have a separate vision document 
          and supplementary requirements specification. A text 
          annotation on diagrams may be used to refer to these if the 
          user finds this helpful.</para>

          <warning>

            <para>The documentation tab includes a <literal>
            Deprecated</literal> check box. The state of this flag is 
            not preserved over save and load in the current release of 
            ArgoUML</para>

          </warning>

        </sect2>

        <sect2>

          <title>System Boundary Box</title>

          <indexterm><primary>System Boundary Box in Use Case 
          Diagram</primary></indexterm>
          <para>ArgoUML provides a series of tools to provide arbitrary 
          graphical annotation on diagrams (we have already mentioned 
          the text tool). These are found at the right hand end of the 
          editing pane toolbar and are fully documented in the 
          reference manual (see <xref linkend="ch.ref.editpane"/>
          ).</para>

          <para>The rectangle tool can be used to draw the boundary 
          box. Use the button&nbsp;2 context-sensitive <literal>
          Ordering</literal> pop-up menu to place it behind everything 
          else. However there is no way to change its fill color from 
          the default white. You may therefore prefer to draw the 
          boundary box as four lines. This is the method used for the 
          diagrams in this chapter.</para>

          <note>

            <para>The editing pane in ArgoUML has a grid to which 
            objects snap to aid in drawing. The size of this grid and 
            its effect may be altered through the <literal>
            View</literal> menu (using <literal>Adjust Grid</literal> 
            and <literal>Adjust Grid Snap</literal>). This is described 
            fully in the reference manual (see 
            <xref linkend="ch.ref.menu"/>).</para>

          </note>

        </sect2>

      </sect1>

      <sect1 id="s3.tut.req_case_study">

        <title>Case Study</title>

        <sect2>

          <title>Vision Document</title>

          <indexterm><primary>Vision Document</primary><secondary>Case 
          Study</secondary></indexterm>
          <para>A vision document contains more than those things 
          needed for the modeling effort. It also contains financial 
          and scheduling pertinent information. The following sections 
          are those parts of the Vision Document spelled out in 
          <xref linkend="s2.tut.vision_document"/> above. In practice 
          this format need not be followed religiously, but is used 
          here for consistency.</para>

          <sect3>

            <title>Summary</title>

            <para>The company wishes to produce and market a line of 
            ATM devices. The purpose of this project is to produce the 
            hardware and the software to drive it that are both 
            maintainable and robust.</para>

          </sect3>

          <sect3>

            <title>Goals</title>

            <para>To produce better designed products based on newer 
            technology. Follow the MDA philosophy of the OMG by 
            producing first a Platform Independent Model (PIM). As 
            current modeling technology does not admit of maintaining 
            the integrity of the connection between the PIM and 
            Platform Specific Models (PSMs), the PIM will become 
            comparatively stable before the first iteration of the PSM 
            is produced. The software platform will be Java technology. 
            The system will use a simple userid (from ATM card) and 
            password (or PIN) mechanism.</para>

          </sect3>

          <sect3>

            <title>Market Context</title>

            <para>Equipment currently on the market is based on older 
            technology for both hardware and software. This technology 
            has not reached the end of its useful life, making it 
            unlikely that the vendors of that gear are going to update 
            it in the near future. On the other hand newer technology 
            is available that would put us at a competitive advantage 
            if implemented now.</para>

          </sect3>

          <sect3>

            <title>Stakeholders</title>

            <para>Among the stakeholders for this system are the 
            Engineering Department, the Maintenance Department, and the 
            Central Computer Facility. The full list of these 
            stakeholders and the specific individuals representing them 
            are.</para>

            <itemizedlist>

              <listitem>

                <para><emphasis>Engineering</emphasis>.  Bunny, 
                Bugs</para>

              </listitem>

              <listitem>

                <para><emphasis>Maintenance</emphasis>.  Hardy, 
                Oliver</para>

              </listitem>

              <listitem>

                <para><emphasis>Computer Facility</emphasis>.  Laurel, 
                Stanley</para>

              </listitem>

              <listitem>

                <para><emphasis>Chief Executive Officer</emphasis>. 
                 Hun, Atilla The</para>

              </listitem>

              <listitem>

                <para><emphasis>Marketing</emphasis>.  Harry, Oil 
                Can</para>

              </listitem>

            </itemizedlist>

          </sect3>

          <sect3>

            <title>Key Features</title>

            <para>Cash deposit, cash withdrawal, and account inquiries 
            by customers. Customers include people who have accounts at 
            the owning bank as well as people who wish to make 
            withdrawals from accounts in other banks or from credit 
            card accounts.</para>

            <para>Maintenance of the equipment by the bank&apos;s 
            engineers. This action may be initiated by the engineer on 
            a routine basis. It may also be initiated by the equipment 
            that can call the engineer when it detects an internal 
            fault.</para>

            <para>Unloading of deposits and loading of cash by 
            officials of the local bank branch. These actions occur 
            either on a scheduled basis or when the central computer 
            determines that the cash supply is low or the deposit 
            receptacle is liable to be getting full.</para>

            <para>An audit trail for all activities will be maintained 
            and sent periodically to the bank&apos;s central computer. 
            It will be possible for the maintenance engineer to save a 
            copy of the audit trail to a diskette for transporting to 
            the central computer.</para>

            <para>
              Both dialup and leased line support will be provided. 
              The ATM will continue to provide services to customers when 
              communication with the central computer is not available.
            </para>

          </sect3>

          <sect3>

            <title>Constraints</title>

            <para>The project must be completed within nine months. It 
            must cost no more than 1,750,000 USD excluding production 
            costs. Components may be contracted out, but the basic 
            architecture as well as the infrastructure will be designed 
            in house. Close liaison must be maintained between the 
            software development and the design, development and 
            production of the hardware. Neither the hardware nor the 
            software shall be considered the independent variable, but 
            rather they shall be considered equal.</para>

          </sect3>

          <sect3>

            <title>Appendix</title>

            <para>The following are the actors that directly support 
            this vision. Additional actors may be identified later that 
            are needed to support this or that technology. They should 
            not be added to this list unless they are deemed to 
            directly support the vision as described in this 
            document.</para>

            <itemizedlist>

              <listitem>

                <para>Central Computer</para>

              </listitem>

              <listitem>

                <para>Customer</para>

              </listitem>

              <listitem>

                <para>Local Branch Official</para>

              </listitem>

              <listitem>

                <para>Maintenance Engineer</para>

              </listitem>

            </itemizedlist>

            <para>The following are the use cases that directly support 
            this vision. Additional use cases may be identified later 
            that are needed to support this or that technology or to 
            support the use cases listed here. They should not be added 
            to this list unless they are deemed to directly support the 
            vision as described in this document.</para>

            <itemizedlist>

              <listitem>

                <para>Audit</para>

              </listitem>

              <listitem>

                <para>Customer Uses Machine</para>

              </listitem>

              <listitem>

                <para>Maintain Machine</para>

              </listitem>

            </itemizedlist>

          </sect3>

        </sect2>

        <sect2>

          <title>Identifying Actors and Use Cases</title>

          <para>For the ATM case study, we will elaborate on the 
          examples in <xref linkend="s1.tut.req_process_output"/>, 
          <xref linkend="fig.tut.atm_use_case_diagram_include"/> and 
          <xref linkend="fig.tut.atm_use_case_diagram_extend"/>, and 
          progress to identify additional actors and use cases that 
          comprise our model of the ATM system. 
          <xref linkend="fig.tut.atm_use_case_diagram_include"/> and 
          <xref linkend="fig.tut.atm_use_case_diagram_extend"/> 
          exemplified the essential concepts and components of a use 
          case diagram such as, use cases, actors, multiplicity, and 
          include / extend relationships. They showed the relationships 
          between the actors and use cases, and demonstrated how these 
          actors and use cases interact.</para>

          <para>In 
          <xref linkend="fig.tut.atm_use_case_diagram_include"/> we see 
          a use case diagram for an ATM system consisting of &laquo;include&raquo; 
          relationships for the use cases, Maintain ATM and Use ATM. 
          Maintain ATM was further defined by two use cases, 
          &quot;Maintain Equipment&quot; and &quot;Reload ATM&quot;. 
          Use ATM was further defined in terms of the behavior of three 
          simpler use cases: &quot;Deposit Cash&quot;, &quot;Withdraw 
          Cash&quot; and &quot;Query Account&quot;.</para>

          <remark>More to be written...</remark>
        </sect2>

        <sect2>

          <title>Associations (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Diagram Features (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Use Case Specifications (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Supplementary Requirements Specification (To be 
          written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.tut.analysis">

      <title>Analysis</title>


        <para>Analysis is the process of taking the 
        <quote>customer</quote> requirements and re-casting them in the 
        language of, and from the perspective of, a putative 
        solution.</para>

        <para>We are not actually trying the flesh out the detailed 
        solution at this stage. That occurs in the <emphasis>Design 
        Phase</emphasis> (see <xref linkend="ch.tut.design"/>).</para>

        <para>Unlike the boundary between Requirements and Analysis 
        Phases, the boundary between Analysis and Design Phases is 
        inherently blurred. The key is that analysis should define the 
        solution no further than is necessary to specify the 
        requirements in the language of the solution. The model elements in 
        Analysis generally represent a high level of abstraction.</para>

        <para>Once again the <emphasis>recursive</emphasis>, and 
        <emphasis>iterative</emphasis> nature of our process means we 
        will come back to the Analysis phase many times in the 
        future.</para>

      <sect1>

        <title>The Analysis Process</title>

        <para>
          There are three schools of thought on how Analysis
          should be approached.
          The ontologist defines the data (actually the metadata)
          first and worries about processes later.
          The true ontologist would prefer not to have to think
          about processes at all.
          The phenomenonologist reverses this and favors
          process over data.
          The panparadigmist considers both process and data to be
          equally important and addresses both from the start.
        </para>

        <para>
          When it comes to being a purist the ontologist has
          the upper hand.
          It is possible to define and build a database into
          which data can be entered and retrieved without concern for
          what happens to it or is done with it.
          On the other hand implementing a process without having any
          data structures for it to operate on is not very meaningful.
        </para>

        <sect2>

          <title>Class, Responsibilities, and Collaborators (CRC) Cards</title>

          <para>
            The CRC methodology favors the phenomenonologists
            preference for analysis.
            It is the equivalent of starting with the use cases,
            the process aspects (operations) of the class diagrams,
            and scenarios from which sequence diagrams can be initiated.
          </para>

          <para>
            CRC cards and the associated methodology are described
            in detail in <xref linkend="app.crc"/>.
            They are used again in the design phase and are further
            discussed in <xref linkend="ch.tut.design"/>.
          </para>

          <para>
            The strength of CRC cards during analysis.
          <itemizedlist>
            <listitem><para>Common Project Vocabulary -</para></listitem>
            <listitem><para>Spread Domain Knowledge -</para></listitem>
            <listitem><para>Making the Paradigm Shift -</para></listitem>
            <listitem><para>Live Prototyping -</para></listitem>
            <listitem><para>Identifying Holes in Requirements -</para></listitem>
          </itemizedlist>
          </para>

          <para>
            In this phase the group should consist of two or
            three domain experts, one object-oriented technology
            facilitator, and the rest of the group made up of people
            who are responsible for delivering the system.
          </para>

          <para>
            The first time that the Analysis phase occurs a special
            case of the CRC session happens as there are no classes
            or scenarios to choose from to define a CRC session.
            At this point a special type of session known
            as brainstorming is held.
            During this session you identify the initial set of
            classes in the problem domain by using the problem statement
            or requirements document or whatever you know about the
            desired result for a starting point.
            The nouns that are found in whatever you are starting from are
            a good key to an initial set of classes in the system.
            In a brainstorming session there should be little or no
            discussion of the ideas.
            Record them and filter the results after the brainstorming.
            At this stage the distinction between class and object
            is blurred.
          </para>

          <para>
            Once a reasonable set of classes has been defined
            by the group, responsibilities can be added.
            Add responsibilities that are obvious from the requirements
            or the name of the class.
            You don&apos;t need to find them all (or any for that matter).
            The scenarios will make them more obvious.
            The advantage of finding some in the beginning is that
            it helps provide a starting place.
          </para>

          <para>
            Select the initial scenarios from the requirements document
            by examining it&apos;s verbs in much the same way that we scanned
            its nouns earlier.
            Then as many walk through sessions as necessary to complete
            the analysis phase are performed.
          </para>

          <para>
            When is enough of the analysis complete that design can begin?
            When all the different responsibilities are in place
            and the system has become stable.
            After all the normal behavior has been covered, exceptional
            behavior needs to be simulated.
            When you notice that the responsibilities are all in place to
            support the new scenarios, and there is little change to the
            cards, this is a sign the you are ready to start design.
          </para>

        </sect2>

        <sect2>

          <title>Concept Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>System Sequence Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>System Statechart Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Realization Use Case Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Documents (To be written)</title>

          <remark>Use Case Specifications and Supplementary 
          Requirements Specifications recast in solution language. To 
          be written...</remark>
        </sect2>


      </sect1>

      <sect1 id="s1.umlclassdiags">

        <title>Class Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Class Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Class Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Association Classes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1 id="s1.argoclassdiags">

        <title>Creating Class Diagrams in ArgoUML</title>

        <sect2>

          <title>Classes</title>

          <remark>Identifying class diagrams from existing materials 
          (Vision, Use Cases etc). To be written...</remark>
          <sect3>

            <title>Using the Note Icon in the Tool Bar</title>

            <para>Click on your target class. Then click on the note 
            icon. ArgoUML will generate the link automatically.</para>

            <para>You can also right click to add a note as well! Be 
            aware that you can add an undefined number of notes to any 
            one class!</para>

            <warning>

              <para>Be aware that your note will not appear in the 
              source code documentation tab.</para>

            </warning>

          </sect3>

        </sect2>

        <sect2>

          <title>Associations (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Aggregation (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Class Attributes and Operations (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Entering Data Into Attributes and Methods 
            Windows</title>

            <para>Click directly in the class model element and start 
            typing. Do not use the properties window dialog fields&mdash;they 
            are not fully functional and liable to cause you a little 
            frustration.</para>

            <para>
              In fact, it would be interesting to see if you can 
              type stereotypes right into the class attribute box for 
              generating XML diagrams.
            </para>

          </sect3>

          <sect3>

            <title>Class Attributes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Class Operations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Class Features (To be written)</title>

          <sect3>

            <title>Association Classes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Stereotypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1 id="s1.umlseqdiags">

        <title>Sequence Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Sequence Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Identifying Actions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Sequence Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1 id="s1.argoseqdiags">

        <title>Creating Sequence Diagrams in ArgoUML</title>

        <sect2>

          <title>Sequence Diagrams</title>

          <sect3>

            <title>Creating a Sequence Diagram</title>

            <para>Normally, you can just start a sequence diagram right 
            away. On the <literal>Create Diagram</literal> menu choose 
            <literal>Sequence</literal>.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Actions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Sequence Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1 id="s1.umlstatediags">

        <title>Statechart Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Statechart Diagram (To be written)</title>

          <remark>Types of statechart diagram (Moore, Mealy); 
          Hierarchical diagrams. To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Hierarchical Statechart Diagrams (To be 
            written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1 id="s1.argostatediags">

        <title>Creating Statechart Diagrams in ArgoUML</title>

        <sect2>

          <title>Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Creating a Statechart Diagram</title>

            <para>Select a class, then you can create a statechart 
            diagram.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>States (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Editing a Composite State</title>

            <para>When editing a composite state, how do you provide do 
            and event for a composite state?</para>

            <para>The answer is to select a class, then you can create 
            a statechart diagram.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Transitions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Actions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Hierarchical Statechart Diagrams (To be 
            written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Realization Use Cases (To be written)</title>

        <remark>To be written...</remark>
      </sect1>

      <sect1>

        <title>Creating Realization Use Cases in ArgoUML (To be 
        written)</title>

        <remark>To be written...</remark>
      </sect1>

      <sect1>

        <title>Case Study (To be written)</title>

        <para>

          Regardless of which methodology you use, at this time you are
          undoubtedly going to take the problem statement from
          <xref linkend="s3.tut.req_case_study"/>
          and extract the nouns from it.
          This list should be compacted to contain only those nouns that are
          expected to result in a class.
          This effort results in the following.

          <itemizedlist>
            <listitem><para>Account</para></listitem>
            <listitem><para>Audit trail</para></listitem>
            <listitem><para>Bank</para></listitem>
            <listitem><para>Cash</para></listitem>
            <listitem><para>Customer</para></listitem>
          </itemizedlist>
          
        </para>

        <sect2>

          <title>CRC Cards</title>

          <para>
            The project manager convenes a CRC session at which the initial
            set of classes are to be defined.
            The facilitator reminds the participants that we are in the
            analysis phase and are only interested in what needs to be done
            (at the business level) and are to leave out anything that smacks
            of how to do it.
            As a general rule of thumb this means a subset of
            the nouns from the problem statement (see above).
            The group starts with a complete list of all of the nouns in the
            statement, examines each one, and decides which are inappropriate
            crossing them off the list.
            Each class is then assigned to one of the participants.
          </para>

          <para>
            <remark>to be continued</remark>...
          </para>

        </sect2>

        <sect2>

          <title>Concept Class Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying classes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Identifying associations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>System Sequence Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying actions (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>System Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Realization Use Cases (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.tut.design">

      <title>Design</title>

      <para>
        We now have the problem we are trying to solve specified 
        in the language of a putative solution.
        In the Design Phase, we 
        construct all the details of that solution.
      </para>

      <para>
        The blurred boundary between Analysis and Design is 
        reflected in their use of many of the same UML tools.
        In this chapter we will mostly be reusing UML technology we have 
        already met once.
        The big step is casting everything into 
        concrete terms. We move from the abstract concepts of analysis 
        to their concrete realization.
      </para>

      <para>
        Once again the <emphasis>recursive</emphasis>, and 
        <emphasis>iterative</emphasis> nature of our process means we 
        will come back to the Design phase many times in the 
        future.
      </para>

      <sect1>

        <title>The Design Process (To be written)</title>

        <para>
          The design process extends the modeling effort beyond the business
          concerns and into the solutions space.
          It is during this effort that you decide whether you are going to use
          Java, C++, J2EE, CORBA, SOAP, Dial up line, internet connection
          dedicated line, XML, etc.
          Many of these decisions will impact directly the PSM model, others
          may only be reflected in the documents produced.
        </para>

        <para>
          ...
        </para>

        <sect2>

          <title>Class, Responsibilities, and Collaborators (CRC) Cards</title>
          <para>
            Strength of CRC cards during Design
            <itemizedlist>
              <listitem><para>Spreading Objet-Oriented Design Expertise</para></listitem>
              <listitem><para>Design Reviews</para></listitem>
              <listitem><para>Framework for Implementation</para></listitem>
              <listitem><para>Informal Notation</para></listitem>
              <listitem><para>Choice of supporting software components</para></listitem>
              <listitem><para>Performance Requirements</para></listitem>
            </itemizedlist>
          </para>

          <para>
            In this phase developers replace some of the domain experts
            in the group, but there should always be at least one domain
            expert in the group.
          </para>

          <para>
            The focus of the group moves from what is to be done to
            how to do it.
            The classes from the solution domain are added to
            those defined in the analysis phase.
            Think about what classes are needed to make the system work.
            Do you need a List class to hold objects?
            Do you need classes to handle exceptions?
            Do you need wrapper classes for other subsystems?
            New classes that are looked for in this part, are classes
            that support the implementation of the system.
          </para>

          <para>
            During the design phase the distinction between class and object
            becomes important.
            Think about the objects in your scenarios.
            Who creates the objects?
            What happens when it is created and destroyed?
            What is the lifetime of the object vs. the lifetime of the
            information held be the object?
          </para>

          <para>
            Now is the time to look at what information the objects hold
            compared to what is requested from other classes or computed
            on the fly.
            Use the back of the card to record the attributes found for
            the classes.
            Break you responsibilities into subresponsibilities and list the
            subresponsibilities indented under the main responsibilities.
            Move the collaborators next to the subresponsibilities
            that use them.
          </para>

          <para>
            After the Collaborator class on your card list the responsibility
            of the used class that is used in the collaboration.
            After the collaborating responsibilities on your cards, list the
            data passed back by the collaborating object in parenthesis.
          </para>

          <para>
            Redo the scenarios you did in the analysis phase, but know take
            into consideration all of the design heuristics discussed.
            Make up your own scenarios and try them.
          </para>

        </sect2>

        <sect2>

          <title>Package Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Realization Class Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Sequence Diagrams and Collaboration Diagrams (To be 
          written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Statechart Diagrams and Activity Diagrams (To be 
          written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Deployment Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Documents (To be written)</title>

          <remark>System Architecture. To be written...</remark>
        </sect2>

      </sect1>

      <sect1>

        <title>Package Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Package Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Package Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Subpackages (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Adding DataTypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Adding Stereotypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Creating Package Diagrams in ArgoUML</title>

        <sect2>

          <title>Packages</title>

          <remark>How to work out what goes in packages. To be 
          written...</remark>
          <sect3>

            <title>Subpackages (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Relationships between packages (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Dependency (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Generalization (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Realization and Abstraction (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Package Features (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Creating New Datatypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Creating New Stereotypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>More on Class Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Class Diagram (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Class Attributes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Class Operations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Class Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Realization and Abstraction (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>More on Class Diagrams in ArgoUML (To be written)</title>

        <sect2>

          <title>Classes (To be written)</title>

          <remark>More on identifying classes from existing materials 
          and use of stereotypes. To be written...</remark>
        </sect2>

        <sect2>

          <title>Class Attributes and Operations (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Class Attributes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Class Operations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Class Features</title>

          <sect3>

            <title>Operations on Interfaces</title>

            <sect4>

              <title>Interfaces that extend interfaces</title>

              <para>Add a unnamed interface to the current classdiagram 
              by single-clicking on the interface icon in the tool bar 
              and then clicking at the diagram pane (see 
              <xref linkend="fig.tut.iftool"/>).</para>

              <figure float="1" id="fig.tut.iftool">

                <title>Selecting the Interface tool</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/iftool.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>Then double click on the interfaces name field to 
              change it&apos;s name as shown in 
              <xref linkend="fig.tut.if"/></para>

              <figure float="1" id="fig.tut.if">

                <title>Interface model element on the Class Diagram</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/if.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>and type a name for it (like <literal>
              TestInterface</literal> in this case). Press 
              <quote>Enter</quote> when the name is complete. (You 
              could also enter the name by going to the Properties Tab 
              in the Details Pane after adding the interface.)</para>

              <para>Add another interface with a different name by repeating 
              the last 2 steps. Then single-click on the Generalization 
              icon in the tool bar as shown in 
              <xref linkend="fig.tut.generalize"/>.</para>

              <figure float="1" id="fig.tut.generalize">

                <title>Generalization on the Class Diagram tool 
                bar</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/generalize.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>Move the mouse pointer to the subinterface, press 
              the left mouse button and drag the generalization to the 
              superinterface, where you release the mouse button. 
              The screenshot of <xref linkend="fig.tut.ifgen"/> shows how your 
              diagram should look now.</para>

              <figure float="1" id="fig.tut.ifgen">

                <title>Generalization between two Interfaces.</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/tutorial/ifgen.gif"
                 format="GIF"/></imageobject></mediaobject></screenshot>
              </figure>

              <para>By clicking on the subinterface and the source tab 
              properties pane, and then selecting Java Notation for the 
              source tab, you can see that the interface actually 
              extends it&apos;s superinterface.</para>

            </sect4>

          </sect3>

          <sect3>

            <title>Stereotypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Sequence and Collaboration Diagrams (To be 
        written)</title>

        <note>

          <para>Sequence diagrams does not work in ArgoUML version 
          0.14.</para>

        </note>

        <remark>To be written...</remark>
        <sect2>

          <title>More on the Sequence Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>The Collaboration Diagram (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Messages (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Actions (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Collaboration Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1>

        <title>Creating Collaboration Diagrams in ArgoUML (To be 
        written)</title>

        <sect2>

          <title>Collaboration Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Messages (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Actions (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Advanced Collaboration Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1>

        <title>Statechart Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Statechart Diagram (To be written)</title>

          <remark>More on this. To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Actions (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Transitions (To be written)</title>

            <remark>To be written...</remark>
            <sect4>

              <title>Triggers (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Guards (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Effectss (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

          </sect3>

          <sect3>

            <title>Pseudo States (To be written)</title>

            <remark>To be written...</remark>
            <sect4>

              <title>Junction and Choice (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Fork and Join (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

          </sect3>

          <sect3>

            <title>Hierarchical State Machines (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Models for State History (To be written)</title>

            <remark>Shallow v Deep. To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Creating Statechart Diagrams in ArgoUML (To be 
        written)</title>

        <sect2>

          <title>Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>States (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Transitions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Actions (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Advanced Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Transitions (To be written)</title>

            <remark>To be written...</remark>
            <sect4>

              <title>Triggers (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Guards (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Effectss (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

          </sect3>

          <sect3>

            <title>Pseudo States (To be written)</title>

            <remark>To be written...</remark>
            <sect4>

              <title>Junction and Choice (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

            <sect4>

              <title>Fork and Join (To be written)</title>

              <remark>To be written...</remark>
            </sect4>

          </sect3>

          <sect3>

            <title>Hierarchical State Machines (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>History (To be written)</title>

            <remark>Shallow v Deep. To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1 id="s1.umlactivitydiags">

        <title>Activity Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Activity Diagram (To be written)</title>

          <remark>More on this. To be written...</remark>
          <sect3>

            <title>Action States (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>Creating Activity Diagrams in ArgoUML (To be 
        written)</title>

        <sect2>

          <title>Activity Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Creating an Activity Diagram</title>

            <para>Select a use case or class, then you can create an 
            activity diagram.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Action States (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1>

        <title>Deployment Diagrams (To be written)</title>

        <remark>To be written...</remark>
        <sect2>

          <title>The Deployment Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

      <sect1>

        <title>Creating Deployment Diagrams in ArgoUML (To be 
        written)</title>

        <sect2>

          <title>Nodes (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Node Instances (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Components (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Component Instances (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Relationships between nodes and components (To be 
          written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Dependency (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Associations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Links (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>System Architecture (To be written)</title>

        <remark>To be written...</remark>
      </sect1>

      <sect1>

        <title>Case Study (To be written)</title>

        <sect2>

          <title>CRC Cards (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Packages (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying Packages (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Datatypes and Stereotypes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Class Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying classes (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Identifying associations (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

          <sect3>

            <title>Specifying Attributes and Operations (To be 
            written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Sequence Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying actions (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Collaboration Diagrams (To be written)</title>

          <remark>To be written...</remark>
          <sect3>

            <title>Identifying Messages (To be written)</title>

            <remark>To be written...</remark>
          </sect3>

        </sect2>

        <sect2>

          <title>Statechart Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>Activity Diagrams (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>The Deployment Diagram (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

        <sect2>

          <title>The System Architecture (To be written)</title>

          <remark>To be written...</remark>
        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.tut.build">

      <title>Code Generation, Reverse Engineering, and Round Trip 
      Engineering</title>

      <sect1>

        <title>Introduction</title>

        <para>We now have our design fully specified. With the right 
        simulator we could actually execute the design and see if it 
        works. (ArgoUML does not provide such functionality, but this 
        functionality has been provided in alternative tools.)</para>

        <para>ArgoUML does allow you to generate code from the design 
        in several different programming languages. We, most likely, 
        already in the design had a programming language in mind 
        because some of the design considerations are to care for a 
        specific language.</para>

        <para>The output of this process is the set of files that 
        constitute the program that solves the problem.</para>

        <para>Once again the <emphasis>recursive</emphasis>, and 
        <emphasis>iterative</emphasis> nature of our process means we 
        will come back to the Build phase many times in the 
        future.</para>

        <para>There is also another side to this and that is the 
        reverse engineering side. If we happen to have an old program 
        that we would like to examine then we could take the files and 
        reverse engineer them to create a design. This can be used when 
        trying to understand some not so well documented program or as 
        a quick start for the design work.</para>

        <para>The process of going back and forth between doing changes 
        in the design followed by a code generation and then doing 
        changes in the code followed by a reverse engineering using for 
        every change, the best possible perspective, is called 
        Round-trip Engineering.</para>

      </sect1>

      <sect1>

        <title>Code Generation</title>

        <indexterm><primary>Code Generation</primary></indexterm>
        <para>The output of the Code Generation is the completed 
        program. Depending on the contents of the design, we could also 
        generate Unit test cases.</para>

        <para>To do the work we need the design model, containing both 
        static and dynamic descriptions of the program.</para>

        <sect2>

          <title>Generating Code from the Static Structure</title>

          <indexterm><primary>Generating Code</primary><secondary>from 
          the Static Structure</secondary></indexterm>
          <para>

            It is rather straightforward to do this generation, at 
            least as long as we do it for an object-oriented language. 
            This is some of the basic rules:
            <itemizedlist>

              <listitem>

                <para>A class will become a class.</para>

                <para>In some target languages (like java, c++) they 
                also become files and compilation units.</para>

              </listitem>

              <listitem>

                <para>A generalization will become an 
                inheritance.</para>

                <para>If the target language does not support 
                inheritance and we didn&apos;t address this during the 
                design, some special conversions are required to solve 
                this.</para>

              </listitem>

              <listitem>

                <para>An attribute will become a member variable.</para>

              </listitem>

              <listitem>

                <para>A navigable association will become a member 
                variable.</para>

                <para>Depending on the target language, target 
                platform, and the association multiplicities this will 
                be a pointer, a reference, a collection class, an entry 
                in some table or map.</para>

              </listitem>

              <listitem>

                <para>A non-abstract operation in a class will become a 
                method.</para>

              </listitem>

              <listitem>

                <para>An abstract operation in a class will become an 
                abstract method.</para>

              </listitem>

              <listitem>

                <para>An in parameter in an operation will become a 
                parameter in the method.</para>

                <para>For simple types (int, boolean), this is the 
                normal case. For C++, these will probably const 
                classes. For Java, this cannot be enforced for 
                classes.</para>

              </listitem>

              <listitem>

                <para>An out or in/out parameter in an operation will 
                become a referenced parameter in the method.</para>

                <para>For C++, these will be referenced non-const 
                parameters. For Java classes, this is the default. 
                Simple types (int, boolean) must, in java, be converted 
                to an object of a corresponding class (Integer, 
                Boolean).</para>

              </listitem>

              <listitem>

                <para>The visibilities of the attributes, associations, 
                and operations will become visibilities on the member 
                variables or methods.</para>

              </listitem>

              <listitem>

                <para>Packages will become directories, namespaces, or 
                both.</para>

              </listitem>

            </itemizedlist>

          </para>

        </sect2>

        <sect2>

          <title>Generating code from interactions and state 
          machines</title>

          <indexterm><primary>Generating Code</primary><secondary>from 
          Sequence Diagrams</secondary></indexterm>
          <indexterm><primary>Generating Code</primary><secondary>from 
          Interactions</secondary></indexterm>
          <indexterm><primary>Generating Code</primary><secondary>from 
          Collaboration Diagrams</secondary></indexterm>
          <indexterm><primary>Generating Code</primary><secondary>from 
          Statechart Diagrams</secondary></indexterm>
          <para>This conversion is not as straight-forward as the 
          conversion of the static structure. It is much more depending 
          on the target language and target platform.</para>

          <para>

            In general it is only possible to say the following for 
            interactions:
            <itemizedlist>

              <listitem>

                <para>A message is converted into a function 
                call.</para>

                <para>The class of the recipient will have to have a 
                function with the correct name and signature.</para>

                <para>The sender function in the class of the sender 
                will have a call to the function in the 
                recipient.</para>

              </listitem>

              <listitem>

                <para>An asynchronous message is converted to either 
                posting a message to be handled by some other thread or 
                a function call to a function that starts a new 
                thread.</para>

              </listitem>

            </itemizedlist>

          </para>

          <para>

            The following describes one possible way to generate state 
            machines:
            <itemizedlist>

              <listitem>

                <para>A State Machine is generated to a set of member 
                variables that each method in this class refer to when 
                deciding behavior.</para>

              </listitem>

              <listitem>

                <para>A State is generated to a closed set of 
                combination of values on these member variables.</para>

              </listitem>

              <listitem>

                <para>An Event is generated as a call to a member 
                method that can change the state.</para>

                <para>These methods would then typically have one big 
                switch statement splitting on the current state.</para>

              </listitem>

              <listitem>

                <para>A Guard is generated to an <symbol>if</symbol> 
                statement in the event member method in the branch for 
                the correct state.</para>

              </listitem>

              <listitem>

                <para>A Transition is generated as an assignment of 
                some state variable.</para>

              </listitem>

              <listitem>

                <para>An Action is generated as a function call.</para>

              </listitem>

            </itemizedlist>

          </para>

        </sect2>

      </sect1>

      <sect1>

        <title>Code Generation in ArgoUML</title>

        <sect2>

          <title>Static Structure</title>

          <para>Most of the generation can be done automatically by the 
          provided language modules. Files are generated in a directory 
          hierarchy that need to be filled in by the actual code.</para>

        </sect2>

        <sect2>

          <title>Interactions and statechart diagrams</title>

          <para>There is currently no support for this in ArgoUML, not 
          for any language.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Reverse Engineering</title>

        <indexterm><primary>Reverse Engineering</primary></indexterm>
        <para>

          Reverse Engineering is used for two main purposes:
          <orderedlist>

            <listitem>

              <para>To get previously developed classed into the model 
              to build upon.</para>

            </listitem>

            <listitem>

              <para>To get a UML view of previously developed classes 
              to understand how they work.</para>

            </listitem>

          </orderedlist>

        </para>

        <para>Essentially this does the opposite of Code 
        Generation.</para>

      </sect1>

      <sect1>

        <title>Round-Trip Engineering</title>

        <indexterm><primary>Round-Trip Engineering</primary></indexterm>
        <para>Round-Trip Engineering makes it possible to switch 
        perspective while doing the design. Create some classes in a 
        class diagram. Write some code for some of the operations or 
        functions using your favorite editor. Move the operations from 
        one class to another in the class diagram...</para>

        <para>ArgoUML currently does not support this for any 
        language.</para>

      </sect1>

    </chapter>

  </part>

  <part>

    <title>User Interface Reference</title>

    <chapter id="ch.ref.ui">

      <title>Introduction</title>

      <para>This chapter describes the overall behavior of the user 
      interface. Description of the various component parts&mdash;the menu 
      bar, panes and various diagrams&mdash; is in separate chapters.</para>

      <sect1>

        <title>Overview of the Window</title>

        <para><xref linkend="fig.ref.gui_overview"/> shows the main 
        ArgoUML window.</para>

        <para>The titlebar of the window shows the following 4 parts of 
        information, separated from each other by a dash.</para>

        <itemizedlist>

          <listitem>

            <para>The current filename. If no filename for the project 
            is set yet, then the titlebar shows 
            &quot;Unititled&quot;.</para>

          </listitem>

          <listitem>

            <para>The name of the currently active diagram.</para>

          </listitem>

          <listitem>

            <para>The name <quote>ArgoUML</quote>.</para>

          </listitem>

          <listitem>

            <para>An asterisk (*). This item is only present if the 
            current project file is <quote>dirty</quote>, i.e. it is 
            altered, but not yet saved. In other words, if the asterisk 
            is absent, then the current file has not been 
            altered.</para>

          </listitem>

        </itemizedlist>

        <figure float="1" id="fig.ref.gui_overview">

          <title>Overview of the ArgoUML window</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/gui_overview.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>At the top of screen is a <emphasis>menu bar</emphasis>, 
        which is described in <xref linkend="ch.ref.menu"/>. Below that 
        is the <emphasis>toolbar</emphasis>, as described in 
        <xref linkend="ch.ref.toolbar"/>.</para>

        <para>The bulk of the window comprises four sub-windows or 
        <emphasis>panes</emphasis>. Clockwise from top left these are 
        the <emphasis>explorer</emphasis> (see 
        <xref linkend="ch.ref.navpane"/>), <emphasis>editing 
        pane</emphasis> (see <xref linkend="ch.ref.editpane"/>), 
        <emphasis>details pane</emphasis> (see 
        <xref linkend="ch.ref.detpane"/>) and <emphasis>to-do 
        pane</emphasis> (see <xref linkend="ch.ref.todopane"/>). All 4 
        panes have a <emphasis>tool bar</emphasis> at the top (in the 
        <emphasis>details pane</emphasis> it is located under the 
        <emphasis>properties</emphasis> tab). An overview of the panes 
        is given in <xref linkend="s1.ref.panes"/>. Finally at the 
        bottom of the window is a <emphasis>status bar</emphasis> 
        described in <xref linkend="s1.ref.status"/>.</para>

      </sect1>

      <sect1 id="s1.ref.mouse">

        <title>General Mouse Behavior in ArgoUML</title>

        <para>Mouse behavior that is specific to the various panes of 
        ArgoUML (see <xref linkend="s1.ref.panes"/>) or the menu bar, 
        is discussed in the chapters covering those panes and the menu 
        bar. In this section we cover behavior that is general across 
        all of ArgoUML.</para>

        <para>In a number of places in ArgoUML text may be directly 
        edited (for example the constraint editor&mdash;see 
        <xref linkend="s2.ref.details_constraint_editor"/>). The 
        behavior of the mouse when handling text is discussed in the 
        sections that follow.</para>

        <sect2>

          <title>Mouse Button Terminology</title>

          <para>ArgoUML assumes a two button mouse. We will refer to 
          the buttons as <quote>button&nbsp;1</quote> and 
          <quote>button&nbsp;2</quote>. Button&nbsp;1 is the leftmost button on a 
          right-handed mouse, and sometimes referred to as the 
          <emphasis>select</emphasis> button. Button&nbsp;2 is the rightmost 
          button on a right-handed mouse, and is sometimes referred to 
          as the <emphasis>adjust</emphasis> button.</para>

          <para>A single depress and release of a mouse button with the 
          mouse is referred to as a <emphasis>click</emphasis>. Two 
          clicks in quick succession is referred to as a 
          <emphasis>double click</emphasis>. Moving the mouse while 
          holding a button down is referred to as <emphasis>button 
          motion</emphasis> with the starting point being at 
          <emphasis>button down</emphasis> and the end point at 
          <emphasis>button up</emphasis>.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Click</title>

          <para>Clicking on an user-interface object or on a diagram 
          model element may establish many different things. Most of the 
          behaviour is experienced quite intuitive by the user, mainly 
          because the high degree of standardisation, even spanning 
          different computer platforms (Macintosh, PC, UNIX,...). 
          ArgoUML follows the <emphasis>Java Look and Feel Design 
          Guidelines</emphasis> by Sun. See 
          <ulink url="http://java.sun.com/products/jlf/"/>. Hence, 
          behaviour of common user-interface components is generally 
          not discussed in this document.</para>

          <para>On the other hand, mouse actions in a diagram may not 
          seem so intuitive to the user, since it is specific for 
          ArgoUML. Hence they are explained here. In short, clicking 
          selects or activates the object beneath the mouse-pointer, 
          and moves the focus (i.e. navigation).</para>

          <para>More in detail, the button&nbsp;1 click may cause the 
          following result:</para>

          <sect3>

            <title>Selection</title>

            <para>Here button&nbsp;1 is used to choose (select) a model element 
            (in a list or tree or on a diagram) on which subsequent 
            operations will take place. Multiple model elements may be 
            selected by using Shift and/or Ctrl in combination with 
            button&nbsp;1, see <xref linkend="s2.ref.mouse.shift_control"/>. 
            Selection is always clearly indicated by a colored 
            background.</para>

            <para>On a diagram, the selected model element is indicated with 
            colored &quot;blocks&quot; at the corners/ends of the 
            object. Model elements can be selected or deselected in 
            different ways:</para>

            <itemizedlist>

              <listitem>

                <para>Button&nbsp;1 click. Deselects all model elements, and 
                selects the one clicked on.</para>

              </listitem>

              <listitem>

                <para>Button&nbsp;1 motion. Button motion (moving the mouse 
                with the button down) in the diagram, not on any 
                model element, allows to draw a rectangle around model elements 
                which will be selected when the button&nbsp;1 is 
                released.</para>

              </listitem>

              <listitem>

                <para>Menu functions and shortcuts. Many menu 
                operations change selection as side-effect, e.g. 
                creating a new diagram. Many keyboard shortcuts for 
                menu operations change the selection, e.g. Ctrl-A, 
                which stands for the <literal>Select All</literal> 
                function.</para>

              </listitem>

            </itemizedlist>

          </sect3>

          <sect3>

            <title>Activation</title>

            <para>Here button&nbsp;1 is used to activate the user interface 
            component, e.g. a button. The object is usually highlighted 
            when the mouse button is pressed and then activated when 
            the mouse button is released. Activating an user-interface 
            object means that its function is executed.</para>

          </sect3>

          <sect3>

            <title>Navigation</title>

            <para>Here button&nbsp;1 is used to move the focus from one user 
            interface component or diagram model element to another. It is 
            better known under the term keyboard focus. This because 
            keyboard commands usually work on the model element that has the 
            focus. The focus is indicated by a (hardly visible) box 
            around the model element, or for a text entry box, by a flashing 
            cursor.</para>

          </sect3>

          <sect3>

            <title>General Behavior When Editing Text</title>

            <para>Here button&nbsp;1 is used to select the point within the 
            text at which operations (text entry and deletion) will 
            take place.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Double Click</title>

          <para>The behavior of button&nbsp;1 double click varies betweens 
          panes and is discussed in their chapters.</para>

          <sect3>

            <title>General Behavior When Editing Text</title>

            <para>Here button&nbsp;1 double click is used to select a 
            complete word, or other syntactic unit within the text. 
            Subsequent operations (text entry and deletion) will 
            replace the selected text.</para>

          </sect3>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Motion</title>

          <sect3>

            <title>General Behavior When Editing Text</title>

            <para>Here button&nbsp;1 motion is used to select a range of 
            text. Subsequent operations (text entry and deletion) will 
            replace the selected text.</para>

          </sect3>

        </sect2>

        <sect2 id="s2.ref.mouse.shift_control">

          <title>Shift and Ctrl modifiers with Button&nbsp;1</title>

          <sect3>

            <title>Within Lists</title>

            <para>This behavior applies where there is a list of things 
            that may be selected. This includes various dialog boxes, 
            and the to-do pane, where there is a list of to-do items to 
            be selected.</para>

            <para>Where selections are to be made, the SHIFT key is 
            used to with button&nbsp;1 to <emphasis>extend</emphasis> from 
            the original button&nbsp;1 selection to the current 
            position.</para>

            <para>Similarly the CTRL key with button&nbsp;1 is used to 
            add individual items to the current selection. Where 
            Ctrl-button&nbsp;1 is used on an item already selected, that 
            item is removed from the selection.</para>

            <caution>

              <para>Users of Microsoft Windows might be familiar with 
              the use of SHIFT-CTRL-Click (i.e. holding both the 
              Shift and Ctrl key down when clicking), to add 
              sub-lists to an existing selection. ArgoUML does not 
              support this. SHIFT-CTRL-Click will behave as 
              CTRL-Click.</para>

            </caution>

          </sect3>

          <sect3>

            <title>General Behavior When Editing Text</title>

            <para>In a number of places in ArgoUML text may be directly 
            edited (for example when naming a model&mdash;element in the 
            properties pane, or when typing a UML note / comment). Here 
            SHIFT button&nbsp;1 is used to select a range of text from the 
            previously selected point. Subsequent operations (text 
            entry and deletion) will replace the selected text.</para>

          </sect3>

        </sect2>

        <sect2 id="s2.ref.mouse.alt">

          <title>Alt with Button&nbsp;1: Panning</title>

          <para>When holding down the Alt key during button&nbsp;1 down on a 
          diagram, movement of the mouse pans the drawing area. The 
          function is indicated by the mousepointer which turns into a 
          crosshair with arrows.</para>

        </sect2>
        
        <sect2 id="s2.ref.mouse.ctrl">

          <title>Ctrl with Button&nbsp;1: Constrained Drag</title>

          <para>When holding down the Ctrl key while dragging with 
          mouse button&nbsp;1 down on a diagram, the movement of the dragged
          element element will be constrained to one of eight 
          cardinal directions : North, South, East, West, NE, SE, SW, NW.
          </para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Actions</title>

          <para>Button&nbsp;2 actions are all dependent on the pane or menu 
          bar, and discussed in their various chapters.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Double Click</title>

          <para>Button&nbsp;2 actions are all dependent on the pane or menu 
          bar, and discussed in their various chapters.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Motion</title>

          <para>Button&nbsp;2 actions are all dependent on the pane or menu 
          bar, and discussed in their various chapters.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.panes">

        <title>General Information About Panes</title>

        <para>The four sub-windows of the main ArgoUML window are 
        called <emphasis>panes</emphasis>. Clockwise from top left 
        these are the <emphasis>explorer</emphasis> (see 
        <xref linkend="ch.ref.navpane"/>), <emphasis>editing 
        pane</emphasis> (see <xref linkend="ch.ref.editpane"/>), 
        <emphasis>details pane</emphasis> (see 
        <xref linkend="ch.ref.detpane"/>) and <emphasis>to-do 
        pane</emphasis> (see <xref linkend="ch.ref.todopane"/>). At the 
        top the editing pane is a <emphasis>tool bar</emphasis>.</para>

        <sect2>

          <title>Re-sizing Panes</title>

          <para>You can re-size panes by dragging on the divider bars 
          between them. To indicate this possibility, the mouse cursor 
          changes shape when hovering over the divider bars.</para>

          <para>In addition you will see there are two small left 
          pointing arrows within the vertical divider bars, one at the 
          top of the vertical divider bar between explorer and editing 
          pane and one at the top of the vertical divider bar between 
          to-do pane and details pane. Button&nbsp;1 click on the first of 
          these will expand the editing pane to the full width of the 
          window, button&nbsp;1 click on the second will expand the details 
          pane to the full width of the window.</para>

          <para>There is also a small downward pointing arrow within 
          the horizontal divider bar at its leftmost end. Clicking on 
          this will expand the explorer and editing panes to the full 
          depth of the window.</para>

          <para>By using both the top arrow on the vertical divider and 
          the arrow on the horizontal divider, it is possible to expand 
          the editing pane to use the entire window.</para>

          <para>The original configuration can be restored by clicking 
          again on these arrows, which are now located at the edge of 
          the window.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.status">

        <title>The status bar</title>

        <para>The status bar is at the very bottom of the ArgoUML 
        window and is used to display short advisory messages. In 
        general such messages are self explanatory. It is e.g. used for 
        displaying parsing error messages in case a text entered on the 
        diagram can not be interpreted.</para>

      </sect1>

    </chapter>

    <chapter id="ch.ref.toolbar">

      <title>The Toolbar</title>

      <section>

        <title>File operations</title>

        <para>These buttons have identical functions as their 
        counterparts in the <literal>File</literal> menu.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/new.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New</literal> See for a full description 
            <xref linkend="s2.ref.menu_new"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/open_project.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Open Project...</literal> See for a full 
            description <xref linkend="s2.ref.menu_open_project"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/save_project.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Save Project</literal> See for a full description 
            <xref linkend="s2.ref.menu_save_project"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/properties.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Project Properties</literal> 
            See for a full description
            <xref linkend="s2.ref.menu_properties"/>.
            </para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/print.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Print</literal> See for a full description 
            <xref linkend="s2.ref.menu_print"/>.</para>

          </listitem>

        </itemizedlist>

      </section>

      <section>

        <title>Edit operations</title>

        <para>These buttons have identical functions as their 
        counterparts in the <literal>Edit</literal> menu.</para>

        <itemizedlist>

<!--      <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/cut.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Cut</literal> See for a full description 
            <xref linkend="s2.ref.menu_cut"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/copy.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Copy</literal> See for a full description 
            <xref linkend="s2.ref.menu_copy"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/paste.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Paste</literal> See for a full description 
            <xref linkend="s2.ref.menu_paste"/>.</para>

          </listitem>
-->
          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/remove_from_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Remove From Diagram</literal> See for a full 
            description 
            <xref linkend="s2.menu_edit_remove_from_diagram"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/delete_from_model.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Delete From Model</literal> See for a full 
            description 
            <xref linkend="s2.menu_edit_delete_from_model"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/configure_perspectives.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Configure Perspectives</literal> See for a full 
            description 
            <xref linkend="s2.menu_edit_configure_perspectives"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/settings.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Settings</literal> See for a full 
            description 
            <xref linkend="s2.ref.menu_settings"/>.</para>

          </listitem>

<!-- 
          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/navigate_back.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Navigate Back</literal> See for a full description 
            <xref linkend="s2.ref.menu_select"/>.</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/navigate_forward.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Navigate Forward</literal> See for a full 
            description <xref linkend="s2.ref.menu_select"/>.</para>

          </listitem>
 -->
 
        </itemizedlist>

      </section>

      <section>

        <title>View operations</title>

        <para>The <literal>Find...</literal> button has identical 
        behaviour as its counterpart in the <literal>View</literal> 
        menu. The <literal>Zoom</literal> button is a more luxurously 
        version of the function in the <literal>View</literal> 
        menu.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/find.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Find...</literal> See for a full description 
            <xref linkend="s2.ref.menu_find"/>.</para>

          </listitem>

          <listitem>

            <para>

              <guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/zoom.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon>
               
              <literal>Zoom</literal>
               This is a different version of the menu-item for 
              zooming, as described in 
              <xref linkend="s2.ref.menu_zoom"/>
              . Clicking with button&nbsp;1 on the zoom-icon opens a panel 
              as in the figure below.
              <figure float="1" id="fig.ref.toolbar_zoom">

                <title>The Zoom slider on the Toolbar</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/toolbar_zoom_slider.png"
                 format="PNG"/></imageobject></mediaobject></screenshot>
              </figure>

              Once the panel is open, the following actions are 
              possible:
            </para>

            <itemizedlist>

              <listitem>

                <para>Clicking with button&nbsp;1 on the &quot;knob&quot; 
                followed by button&nbsp;1 movement will adjust the 
                zoomfactor.</para>

              </listitem>

              <listitem>

                <para>Clicking with button&nbsp;1 on the shown percentage 
                allows editing the given zoomfactor (in percent) 
                directly with the keyboard. Double clicking on the 
                value shown selects the whole entry for easy 
                overtyping.</para>

              </listitem>

              <listitem>

                <para>Clicking with button&nbsp;1 below or above the knob 
                increases or decreass the zoom factor with 1%. Use this 
                function to easily fine-adjust the percentage.</para>

              </listitem>

              <listitem>

                <para>Clicking with button&nbsp;1 or button&nbsp;2 on the 
                <literal>Zoom</literal> tool, or anywhere outside the 
                slider panel closes the panel.</para>

              </listitem>

              <listitem>

                <para>The keyboard can be used to operate the Zoom 
                Slider as follows: When the <literal>Zoom</literal> 
                icon in the toolbar has the focus (indicated by the 
                thin blue box around it), then pressing the <keycap>
                spacebar</keycap> opens the zoon slider panel. Use the 
                <keycap>arrow</keycap> keys to increase and decrease 
                the percentage 1 by 1. Use <keycap>Shift-Tab</keycap> 
                to set the focus to the percentage box, where you can 
                edit the given value directly. Pressing <keycap>
                Enter</keycap> activates the changed value. When the 
                &quot;knob&quot; has the focus, pressing <keycap>
                PageUp</keycap>/<keycap>PageDown</keycap> 
                increases/decreases the percentage by some amount. Pressing 
                <keycap>Home</keycap> sets the percentage to 300%, and 
                <keycap>End</keycap> sets it to 25%.</para>

              </listitem>

            </itemizedlist>

          </listitem>

        </itemizedlist>

      </section>

      <section id="ch.ref.toolbar.create">

        <title>Create operations</title>

        <para>These buttons have identical functions as their 
        counterparts in the <literal>Create</literal> menu.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/use_case_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Use Case Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.use_case_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/class_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Class Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.class_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/sequence_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Sequence Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.sequence_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/collaboration_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Collaboration Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.collaboration_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/state_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Statechart Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.state_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/activity_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Activity Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.activity_diagram"/>
            .</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/deployment_diagram.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Deployment Diagram</literal> See for a full 
            description 
            <xref linkend="s2.ref.create.diagram.deployment_diagram"/>
            .</para>

          </listitem>

        </itemizedlist>

      </section>

    </chapter>

    <chapter id="ch.ref.menu">

      <title>The Menu bar</title>

      <sect1>

        <title>Introduction</title>

        <para>An important principle behind ArgoUML is that actions 
        should be able to be invoked in whatever way the user finds 
        convenient. As a result many (but not all) actions that can be 
        carried out on the menu can be carried out in other ways as 
        well under ArgoUML.</para>

        <para>A number of the common menu entries are also available 
        through keyboard shortcuts.</para>

        <para>It is also be possible to navigate the menu from the 
        keyboard. Each level of each menu is identified by a letter 
        (shown underlined in the menu or entry name from the moment the 
        ALT key is pressed). This sequence of letters while holding 
        down the ALT key selects the entry. 
        </para>

        <para>The following is an explanation of why the menuitems are 
        grouped as they are.</para>

        <para>

          <itemizedlist>

            <listitem>

              <para>The <emphasis>File</emphasis> menu contains 
              operations that affect on the whole project/file. All the 
              items in this menu can be explained as such.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Edit</emphasis> menu is generally 
              intended for editing the model or changing the content of 
              a diagram. It also contains functions to enable editing, 
              like e.g. selecting. This menu is not intended for 
              diagram layout functions. Most functions here do 
              something with the selected modelelement and diagram. The 
              items &quot;Configure Perspectives...&quot;
              and &quot;Settings...&quot; are a bit different,
              since they adjust the way ArgoUML works - but they do not 
              belong in the File menu, since their settings are not
              stored in the project.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>View</emphasis> menu is for functions 
              that do never alter the model, nor the diagram layout, 
              only the way you view the diagram. A good example is
              &quot;zoom&quot;. 
              Also navigational functions belong here, e.g. &quot;Find&quot; 
              and &quot;Goto Diagram...&quot;. All changes of settings 
              in this menu apply to all diagrams (e.g. zoom).</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Create</emphasis> menu contains all 
              possible diagrams that can be created. 
              These functions are
              context dependend, since they work on the 
              selected modelelement.
              </para>

            </listitem>

            <listitem>

              <para>The <emphasis>Arrange</emphasis> menu allows layout 
              changes in the current diagram, which is not the same as 
              the items in the View menu. Functions here can not alter 
              the UML model.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Generation</emphasis> menu is for 
              Code Generation. The functions here work either on the 
              selected modelelements, or on the whole project.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Critique</emphasis> menu is specific 
              for settings related to critics, 
              which apply for all  projects.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Tools</emphasis> menu is currently 
              empty. If 
              plugins are installed, then their functions appear 
              here.</para>

            </listitem>

            <listitem>

              <para>The <emphasis>Help</emphasis> menu contains the 
              usual &quot;information&quot; and 
              &quot;about&quot;.</para>

            </listitem>

          </itemizedlist>

        </para>

      </sect1>

      <sect1 id="s1.ref.menu_mouse">

        <title>Mouse Behavior in the Menu Bar</title>

        <para>Behavior of the mouse in general, and the naming of the 
        buttons is covered in the chapter on the overall user interface 
        (see <xref linkend="s1.ref.mouse"/>). There is no ArgoUML 
        specific behaviour for the menu.</para>

      </sect1>

      <sect1>

        <title>The File Menu</title>

        <para>These are actions concerned with input and output and the 
        overall management of projects and the ArgoUML system.</para>

        <sect2 id="s2.ref.menu_new">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/new.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New</title>

          <indexterm><primary>New</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-N</secondary></indexterm>
          <para>Shortcut Ctrl-N.</para>

          <para>This initializes a new project within ArgoUML. The 
          project is created without a the name. It contains a 
          (top-level) <literal>Model</literal> named <literal>
          untitledModel</literal> and two empty diagrams: a class 
          diagram and a use case diagram.</para>

          <caution>

            <para><literal>untitledModel</literal> is not a 
            conventional model name (most processes suggest models 
            should be build from lower case letters). ArgoUML permits 
            you to use any case letters, but a critic will trigger to 
            warn that this is not conventional. See 
            <xref linkend="s1.ref.model"/> for a discussion of 
            this.</para>

          </caution>

          <para>If the model has been altered (as indicated by the 
          &quot;*&quot; in the titlebar of ArgoUML&apos;s window), then 
          activating the &quot;New&quot; function is potentionally not 
          the user&apos;s intention, since it will erase the changes. 
          Hence a confirmation dialog appears to allow the user to save 
          his work first, or cancel the operation completely.</para>

          <figure float="1">

            <title>The confirmation dialog for <literal>
            New</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_dialog_confirm_new.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2 id="s2.ref.menu_open_project">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/open_project.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Open Project...</title>

          <indexterm><primary>Open Project...</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-O</secondary></indexterm>
          <para>Shortcut Ctrl-O.</para>

          <para>This opens an existing project from a file. Selecting 
          this menu option will open a file selection dialog (see 
          <xref linkend="fig.ref.menu_open_project"/>).</para>

          <figure float="1" id="fig.ref.menu_open_project">

            <title>The file selection dialog for <literal>
            Open Project...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_open_project.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The main body of the dialog is a text area with a 
          listing of all directories and files in the currently 
          selected directory which match the current filter (see 
          below).</para>

          <para>Navigating in the directory tree is possible by 
          selecting a directory in the drop down selector at the top of 
          this dialog. Navigating deeper in the tree may be done by 
          double clicking button&nbsp;1 on the directory shown in the main 
          text area.</para>

          <para>In the lower portion of the dialog is a text box 
          labeled <literal>File name:</literal> for the name of the 
          file to be opened. The file name may be typed directly in 
          here, or selected from the directory listing above using 
          button&nbsp;1 click.</para>

          <para>Beneath this is a drop down selector labeled <literal>
          Files of type:</literal> to specify a filter on the files to 
          be shown in the directory listing. Only files that match the 
          filter are listed. The available filters are listed below. 
          The default filter is the first one, 
          which combines all available formats.</para>

          <itemizedlist>

            <listitem>
              <para>ArgoUML file (*.zargo, *.uml, *.xmi, *.xml, *.zip)</para>
            </listitem>

            <listitem>
              <para>ArgoUML compressed project file (*.zargo)</para>
            </listitem>

            <listitem>
              <para>ArgoUML project file (*.uml)</para>
            </listitem>

            <listitem>
              <para>XML Metadata Interchange (*.xmi)</para>
            </listitem>
            
            <listitem>
              <para>XML Metadata Interchange (*.xml)</para>
            </listitem>
            
            <listitem>
              <para>XMI compressed project file (*.zip)</para>
            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="s2.ref.menu_save_project">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/save_project.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Save Project</title>

          <indexterm><primary>Save Project</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-S</secondary></indexterm>
          <para>Shortcut Ctrl-S.</para>

          <para>This saves the project using its current file name. Use 
          <literal>Save Project As...</literal> to save the project to a 
          different file. If no filename is given yet (e.g. after 
          <literal>New</literal>), then this function works exactly as 
          <literal>Save Project As...</literal>.</para>

          <note>

            <para>In certain circumstances, there is nothing to save, 
            and this menuitem is downlighted. E.g. when the user did 
            not yet alter a loaded project. The presence of a 
            <quote>*</quote> in the titlebar of ArgoUML&apos;s window 
            indicates that the current project is <quote>dirty</quote> 
            (has been altered), and can be saved.</para>

          </note>

        </sect2>

        <sect2 id="s2.ref.menu_save_project_as">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/save_project_as.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Save Project As...</title>

          <para>This opens a dialog allowing you to save the project 
          under a different file name (or to specify a file name for 
          the first time if the project is a new project).</para>

          <para>The dialog box is almost identical to that for <literal>
          Open Project</literal> (see 
          <xref linkend="fig.ref.menu_open_project"/>). The extension 
          of the filename is automatically set.</para>

        </sect2>

        <sect2 id="s2.ref.menu_revert_to_saved">

          <title>Revert to Saved</title>

          <para>This menu-item allows you to throw away all your recent 
          changes, and reload the last saved version of the current 
          project. It works a bit like an <literal>Undo</literal> 
          feature, but only restores changes done since the last time 
          the file was saved.</para>

          <para>This menu-item is downlighted unless the currentproject 
          has been saved or loaded before (i.e. it has a name), and it 
          has been altered.</para>

          <para>When this menu-item is activated, a small confirmation 
          dialog box opens, as shown in the figure below. This warning 
          that all recent changes will be discarded, is needed because 
          the action can not be undone. Selecting <literal>No</literal> 
          cancels the whole action as if you did not select the 
          menu-item in the first place. Selecting <literal>
          Yes</literal> reloads the last saved file.</para>

          <figure float="1" id="fig.ref.menu_revert_to_saved">

            <title>The warning dialog for Revert to Saved.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_revert_to_saved.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2>

          <title>Import XMI...</title>

          <para>This menu-item allows to load an 
          UML 1.3 or 1.4 model which was exported by e.g. another tool,
          as a XMI file, according the XMI V1.0, V1.1 or V1.2 standard. 
          The extension of such file should be <literal>.xmi</literal>.
          </para>

          <para>If the model has been altered (as indicated by the 
          &quot;*&quot; in the titlebar of ArgoUML&apos;s window), then 
          activating the &quot;Import XMI...&quot; 
          function is potentionally not 
          the user&apos;s intention, since it will erase the changes. 
          Hence a confirmation dialog appears to allow the user to save 
          his work first, or cancel the operation completely.</para>

          <figure float="1">

            <title>The confirmation dialog for <literal>
            Import XMI...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_dialog_confirm_new.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>When the menu is activated, the standard filechooser 
          appears, see <xref linkend="fig.ref.menu_import_xmi"/>.
          Beware the fact that this file will only contain the model, 
          not any diagram layout. Hence, 
          the new project will not contain any diagrams.</para>

          <figure float="1" id="fig.ref.menu_import_xmi">

            <title>The dialog for <literal>
            Import XMI...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_import_xmi.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2>

          <title>Export XMI...</title>

          <para>This menu-item allows to save the complete structure of 
          the UML 1.4 model as a XMI file, according the XMI V1.2 standard. 
          Beware the fact that this file will only contain the model, 
          not any diagram layout. Hence, if the XMI file is reloaded 
          with the <literal>File - Open Project...</literal> menu, then 
          the diagrams are lost.</para>

          <para>When the menu is activated, the standard filechooser 
          appears, see <xref linkend="fig.ref.menu_export_xmi"/>.</para>

          <figure float="1" id="fig.ref.menu_export_xmi">

            <title>The dialog for <literal>
            Export XMI...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_export_xmi.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2 id="s3.ref.menu_import_sources">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/import_sources.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Import Sources...</title>

          <para>A very powerful feature of ArgoUML is that it can 
          <quote>Reverse Engineer</quote> Java code to yield a class 
          diagram. This sub-menu entry specifies Java code to be 
          imported for reverse engineering.</para>

          <para>The dialog box is similar to that for <literal>
          Open Project</literal> (see 
          <xref linkend="fig.ref.menu_open_project"/>), but with two 
          extra tabs placed alongside the directory listing, as shown 
          in <xref linkend="fig.ref.menu_import_sources"/>).</para>

          <figure float="1" id="fig.ref.menu_import_sources">

            <title>The file selection dialog for <literal>
            Import Sources...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_import_sources.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>Those fields that are the same as <literal>
          Open Project</literal> behave in the same way (see 
          <xref linkend="s2.ref.menu_open_project"/>).</para>

          <para>Next to the &quot;All Files&quot; file filter, there is 
          the default filter &quot;Java Source File 
          (*.java)&quot;.</para>

          <para>The first of the two tabs is labeled <literal>
          General</literal> and is selected by button&nbsp;1 click on its 
          tab. It provides a combo box for the language selection (in 
          V0.18 of ArgoUML only Java can be chosen), and the following 
          selections:</para>

          <itemizedlist>

            <listitem>

              <para><literal>Descend directories recursively</literal>. 
              If enabled (the default), reverse engineering will track 
              through sub-directories for any further Java files. If 
              not it will restrict to the selected directory.</para>

            </listitem>

            <listitem>

              <para><literal>Changed/new files only</literal>. 
              If enabled (the default), only changed and new files are imported. 
              If not all classes will be replaced.</para>

            </listitem>

            <listitem>

              <para><literal>Create diagrams from imported 
              code</literal>. If you unselect this, then no diagrams 
              are created, i.e. all data will only be visible in the 
              explorer.</para>

            </listitem>

            <listitem>

              <para><literal>Minimise Class icons in 
              diagrams</literal>. If enabled, then the attributes and 
              operations compartiments will not be shown in the classes 
              on the generated class diagrams. Note: This item is 
              checked by default, and is overseen by many users, which 
              are then surprised by the result.</para>

            </listitem>

            <listitem>

              <para><literal>Perform Automatic Diagram 
              Layout</literal>. If selected, then ArgoUML will do its 
              best to layout the generated diagrams automatically. If 
              not, then all items will be placed at the top left corner 
              of the diagram.</para>

            </listitem>

            <listitem>

              <para><literal>Level of import detail: Classifiers only / 
              Classifiers plus feature specifications / Full 
              import</literal>. The latter is the default.</para>

            </listitem>

            <listitem>

              <para><literal>Import source file encoding:</literal>. 
              The value <literal>Cp1252</literal> is often the default. 
              This string represents the <literal>coded character set 
              identifier (CCSID)</literal>.</para>

            </listitem>

          </itemizedlist>

          <para>The second of the two tabs is labeled <literal>
          Java</literal> and is selected by button&nbsp;1 click on its tab. 
          It provides two pairs of radio boxes.</para>

          <itemizedlist>

            <listitem>

              <para>The first radio box allows selection between 
              modeling attributes of Java classes as UML attributes 
              (the default) or as UML associations to the class 
              specified.</para>

            </listitem>

            <listitem>

              <para>The second radio box allows selection between 
              modeling arrays as new datatypes in their own right (the 
              default) or as their base datatype with 
              multiplicity.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/page_setup.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Page Setup...</title>

          <indexterm><primary>Page Setup ...</primary></indexterm>
          <para>This brings up the standard dialog box provided by the 
          operating system to adjust printer paper size, orientation, 
          and other options.</para>

        </sect2>

        <sect2 id="s2.ref.menu_print">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/print.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Print...</title>

          <indexterm><primary>Print ...</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-P</secondary></indexterm>
          <para>Shortcut Ctrl-P.</para>

          <para>This brings up the standard dialog box provided by the 
          operating system allowing the current diagram to be printed 
          out.</para>

          <para>In some cases, when the printing is started, the dialog 
          box of <xref linkend="fig.ref.menu_diagram_exceeds_page"/> 
          appears. Selecting the &quot;Fit to page&quot; button does 
          print the whole diagram fitted on one page by scaling it 
          down. Which might cause all text to be too small to read in 
          case of big diagrams, but it is a quick and easy way to get 
          an usable printout. Selecting the &quot;Multiple pages&quot; 
          option does print unscaled, by dividing the diagram in 
          pieces, on as many pages as needed. Pressing the close button 
          of the dialog does the former option.</para>

          <figure float="1" id="fig.ref.menu_diagram_exceeds_page">

            <title>The diagram exceeds page size dialog.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_diagram_exceeds_page.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <warning>

            <para>If the current diagram contains no selected 
            model elements, then the whole diagram is printed. However, if 
            one or more model elements are selected, then only the area they 
            cover is printed! If scaling is selected (by the &quot;Fit 
            to page&quot; choice in the dialog box descibed above), 
            then the scaling is done on basis of the selected model elements 
            only. If scaling is not chosen (or in case it is not 
            needed), then all pages containing a selected model element are 
            printed.</para>

          </warning>

        </sect2>

        <sect2 id="s2.ref.menu_export_graphics">

          <title>Export Graphics...</title>

          <para>This menu entry brings up a dialog box allowing the 
          currently selected diagram (in the editing pane) to be saved 
          in one of a number of graphic formats.</para>

          <para>The dialog box is identical to that for <literal>
          Open Project</literal> (see 
          <xref linkend="fig.ref.menu_open_project"/>), except for the 
          <literal>Files of type:</literal>. The chosen filetype 
          specifies the graphics format used for saving. The filename 
          is automatically extended with the corresponding ending (if 
          not entered already). A default filename is generated based 
          on the diagram name.</para>

          <para>The available graphics types are:</para>

          <itemizedlist>

            <listitem>
              <para>GIF image (*.gif)</para>
            </listitem>
            <listitem>
              <para>Encapsulated Postscript file (*.eps)</para>
            </listitem>
            <listitem>
              <para>PNG image (*.png)</para>
            </listitem>
            <listitem>
              <para>Postscript file (*.ps)</para>
            </listitem>
            <listitem>
              <para>Scalable Vector Graphics file (*.svg)</para>
            </listitem>

          </itemizedlist>

          <para>The graphics format that is selected by default
          is set in the dialog under the menu entry Edit - Settings...</para>

          <!--caution>
            TODO: Is this still true?

            <para>The PNG graphics does not support shadows very well, 
            so maybe it is better to either save in GIF format, or 
            switch shadows off before saving in PNG format.</para>

          </caution-->

        </sect2>
        
        <sect2 id="s2.ref.menu_export_all_graphics">

          <title>Export All Graphics...</title>

          <para>This menu entry brings up a dialog box 
          to select a directory. 
          In this directory, for all diagrams in the current project,
          a graphics file is generated.</para>
          
          <para>The names of the files are deducted from the diagram names.
          The graphics format that is produced
          is set in the dialog under the Edit menu 
          (see <xref linkend="s2.ref.menu_settings"/>).</para>

        </sect2>
        
        <sect2 id="s2.ref.menu_notation">

          <title>Notation</title>

          <para>This sub-menu presents a radio button selection for 
          notation, i.e. the language in which all textual adornments 
          are shown on the diagrams. 
          </para>

          <para>This feature defines the project&apos;s notation language.
          </para>

          <para>There are 2 ways to set the notation language:</para>

          <itemizedlist>

            <listitem>

              <para>In the Edit menu,
              see <xref linkend="s3.ref.menu_settings_notations"/>
              in the notation tab of the settings dialog,
              which defines the default notation language for new projects.
              This choice is stored in the 
              <filename>argo.user.properties</filename> file in the 
              <filename>.argouml</filename> directory under the 
              user&apos;s home directory.
              </para>

            </listitem>

            <listitem>

              <para>In the File menu, item Notation. This determines  
              how all textual adornments of figures 
              on all diagrams 
              of the current project are shown.
              This choice is stored in the project file.
              </para>

            </listitem>

          </itemizedlist>

          <para>The following 2 notations are build in ArgoUML:</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/uml_notation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>UML 1.4</literal>. Uses UML notation as the 
              default notation for every modelelement on any diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/java_notation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Java</literal>. Uses Java notation as the 
              default notation for every modelelement on any diagram.</para>

            </listitem>

          </itemizedlist>

          <para>The following choices are only available if the 
          corresponding plugin languages are installed.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Cpp</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>CSharp</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>PHP</literal>.</para>

            </listitem>

          </itemizedlist>

          <remark>Besides UML, 
          only Java is partly implemented in V0.22 of ArgoUML.</remark>

        </sect2>
        
        <sect2 id="s2.ref.menu_properties">
        
          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/settings.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>
           Project Properties</title>

          <para>This menu entry brings up a dialog box, which allows 
          the user to set various options
          of the currently loaded project.</para>

          <para>All settings in this dialog 
          are stored in the project-file 
          together with the model.</para>
          
          <figure float="1" id="fig.ref.menu_properties_user">

            <title>The dialog for Project Properties - the User tab.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/properties-user.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>
          
          <para>In the User tab, 
          you are able to set the following fields:
          </para>
          
          <itemizedlist>

          <listitem>
          <para>The first field contains 
          the name of the author or responsible 
          for the current project.
          By default the name and email of the creator
          are filled in, 
          so probably you will never need to edit this, 
          but it is possible.
          </para>
          </listitem>
          
          <listitem>
          <para>The Project Description field may contain any text
          that you need to describe the project.
          By default it is empty.</para>
          </listitem>
          
          <listitem>
          <para>The "Last saved with ArgoUML" field 
          indicates the version of ArgoUML 
          that was used to save this project 
          (the last time it was saved).
          This may be usefull if multiple designers have different 
          versions of ArgoUML, 
          which may not be backwards compatible all the time.
          </para>
          </listitem>

          </itemizedlist>
          
          <figure float="1" id="fig.ref.menu_properties_profiles">

            <title>The dialog for Project Properties &ndash; the Profiles tab.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/properties-profiles.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>
          
          <para>In the Profiles tab, you are able change the following settings:
          </para>
          
          <itemizedlist>
          <listitem>
          <para>The type of &ldquo;Stereotype Visualization&rdquo; for the
	  project, which may be textual, small or with big icons.
          </para>
          </listitem>
          
          <listitem>
          <para>The UML profiles which are configured in the project &ndash;
	  model elements of these UML profiles may be referenced in the project.
          </para>
          </listitem>

          </itemizedlist>

          <figure float="1" id="fig.ref.menu_properties_notations">

            <title>The dialog for Project Properties - the Notations tab.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/properties-notations.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>
          
          <para>In the Notations tab, 
          you are able to set the following fields:
          </para>
        
        <itemizedlist>

          <listitem>
            <para>The first field is a combobox that allows
            selection of the project's Notation language.
            By default, it lists UML and Java, 
            but other languages may be added by plugins.
            See the chapter on Notation for more explanation:
            <xref linkend="s1.ref.notation"/>.
            </para>

          </listitem>

          <listitem>
            <para><literal>Use guillemots</literal> (&laquo;&nbsp;&raquo;) for 
                stereotypes (clear by default). By default ArgoUML uses 
                pairs of <emphasis>less than</emphasis> and 
                <emphasis>greater than</emphasis> (&lt;&lt; &gt;&gt;) 
                characters for stereotypes. If this box is checked 
                stereotypes on diagrams are shown between true 
                guillemots (&laquo;&nbsp;&raquo;).</para>

            <para>This feature is presumably added to ArgoUML 
                because guillemots are poorly supported by various 
                fonts, and if they are present, then they are quite 
                small and poorly visible.</para>
          </listitem>
          
          <listitem>
            <para><literal>Show visibility</literal> (clear by 
                default). If this is selected, then ArgoUML will
                show the visibility indicators in front of e.g. attributes
                in the diagram.
                In UML the notation is "+" for public, "-" for private,
                "#" for protected, and "~" for package. 
                E.g. for an attribute, it may show:
                <literal>+newAttr : int</literal>.
            </para>
          </listitem>
          
          <listitem>
                <para><literal>Show multiplicity</literal> (clear by 
                default). If this is selected, then ArgoUML will show 
                the multiplicity of e.g. attributes in the diagram. 
                In UML notation, the multiplicity is shown between [], such as: 
                <literal>+newAttr [0..*] : int</literal>.
                This setting has no impact on showing multiplicity 
                near associationends.
                </para>
              </listitem>

              <listitem>
                <para><literal>Show initial value</literal> (clear by 
                default). If this is selected, then ArgoUML will show
                the initial value of e.g. attributes in the diagram.
                In UML notation, the initial value is shown e.g. like this:
                <literal>+newAttr : int = 1</literal>.
              </para>
              </listitem>

              <listitem>
                <para><literal>Show properties</literal> (clear by 
                default). If this is selected, then ArgoUML will show
                various properties between braces {}.
                E.g. for an attribute, it may show:
                <literal>+newAttr : int { frozen }</literal>.
                </para>
              </listitem>

              <listitem>
                <para><literal>Show types and parameters</literal> 
                (set by default). When this checkbox is unmarked, 
                attributes in classes are shown without type indication, 
                and operations are shown without parameters.
                This feature may be usefull during 
                the analysis phase of your project.
                If all checkmarks in 
                the Notation Tab are unchecked, then
                e.g. for an attribute, ArgoUML may show:
                <literal>newAttr</literal>. And for an operation: 
                <literal>newOperation()</literal>.
                </para>
              </listitem>

              <listitem>
                <para><literal>Show stereotypes in explorer</literal> 
                (clear by default). If this is selected, then ArgoUML will show
                stereotypes next to the icons of the modelelements 
                in the Explorer, i.e. the tree structure at the left hand side.
                </para>
              </listitem>

              <listitem>
                <para><literal>Default shadow width</literal> (set to 1 
                by default). ArgoUML is able to draw all elements 
                on a diagram with a shadow,
                for esthetical reasons. 
                Use this setting to adjust the 
                size of the shadow, used when the modelelement is created.
                The details tab "Presentation" allows to set the shadow per
                modelelement, after they are created, but ArgoUML V0.22 does
                not retain this latter change after save and load.
                </para>
              </listitem>

        </itemizedlist>
          
          <figure float="1" id="fig.ref.menu_properties_diagram_appearance">

            <title>The dialog for Project Properties &ndash; the Diagram Appearance tab.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/properties-diagram-appearance.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>
          
          <para>In the Diagram Appearance tab, you are able change the diagrams
	  font. </para>
          
        </sect2>

        <sect2>

          <title>Most Recent Used Files</title>

          <para>ArgoUML remembers a few of the most recently saved 
          files, and lists them here, to enable loading then in the 
          most simple way.</para>

          <para>The maximum number of files that is listed here, can be 
          adjusted in the <literal>Edit</literal> -&gt; <literal>
          Settings...</literal> menu. The list of files is stored in the 
          <filename>argo.user.properties</filename> file in the 
          <filename>.argouml</filename> directory under the 
          user&apos;s home directory.</para>

        </sect2>

        <sect2>

          <title>Exit</title>

          <indexterm><primary>Exit</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Alt-F4.</secondary></indexterm>
          <para>Shortcut Alt-F4.</para>

          <para>This closes down ArgoUML. A warning message will pop-up 
          if you have a project open with unsaved changes asking if you 
          wish to save it. See 
          <xref linkend="fig.ref.menu_save_changes"/>. The options 
          are:</para>

          <itemizedlist>

            <listitem>

              <para><literal>Yes</literal> (save the project and exit 
              ArgoUML);</para>

            </listitem>

            <listitem>

              <para><literal>No</literal> (do not save the project, but 
              still exit ArgoUML); and</para>

            </listitem>

            <listitem>

              <para><literal>Cancel</literal> (do not save the project 
              and do not exit ArgoUML).</para>

            </listitem>

            <listitem>

              <para>The dialog box can also be closed by clicking in 
              the close button in the window border. The effect is the 
              same as selecting &quot;Cancel&quot;.</para>

            </listitem>

          </itemizedlist>

          <figure float="1" id="fig.ref.menu_save_changes">

            <title>The save changes dialog.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_save_changes.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

      </sect1>

      <sect1>

        <title>The Edit Menu</title>

        <para>This menu provides support for 
        selecting model elements on the editing pane; 
        removal of model elements from diagrams and the model; 
        and control of user settings.</para>

        <sect2 id="s2.ref.menu_select">

          <title>Select</title>

          <para>This sub-menu provides for selection of items on the 
          editing menu. It has the following entries.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Select All</literal> (shortcut Ctrl-A). 
              <indexterm><primary>Select All</primary></indexterm> 
              <indexterm><primary>Shortcut 
              key</primary><secondary>Ctrl-A</secondary></indexterm> 
              Selects all model elements on the current pane or in the 
              current field. The exact behaviour depends on the 
              <literal>current pane</literal> (i.e. the last one you 
              clicked in): explorer pane, editing pane, to-do pane, 
              details pane. One rule applies in all cases though: the 
              selection on the diagram (editing pane) and in the 
              explorer are always synchronised.</para>

              <para>If the editing pane is the <literal>current 
              pane</literal>: First everything in the explorer and on 
              the current diagram is deselected, and then everything 
              that is on the current diagram is selected (and if the 
              same items apear in the explorer, then they are also 
              there indicated as selected, because they are always 
              synchronised).</para>

              <para>If the explorer pane is the <literal>current 
              pane</literal>: All visible items in the explorer pane 
              are selected, and non-visible items are deselected.</para>

              <para>If the to-do pane is the <literal>current 
              pane</literal>: All visible items in the to-do pane are 
              selected, and non-visible items are deselected. In fact, 
              this works the same as for the explorer pane, because 
              both are tree structures.</para>

              <para>If the details pane is the <literal>current 
              pane</literal>: The function only works when the cursor 
              is in certain fields, where selecting is possible, e.g. a 
              Name field. In such a case, the Select All function 
              extends the current selection to the whole field 
              contents.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_back.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Navigate Back</literal>. ArgoUML keeps a record 
              of the model elements that you have been selecting while 
              navigating the model. This button moves you back to the 
              previous one selected. If there are no more previous 
              model elements, the button is grayed out.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_forward.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Navigate Forward</literal>. ArgoUML keeps a 
              record of the model elements that you have been selecting 
              while navigating the model. This button moves you forward 
              to the next one selected (after you have used the 
              Navigate Back button to move back). If there are no more 
              next model elements, the button is grayed out.</para>

            </listitem>

            <listitem>

              <para><literal>Invert Selection</literal>. This inverts 
              the current selection on the <literal>current 
              pane</literal>. More exact: everything that was selected 
              is de-selected and everything that was not selected 
              within the current pane is selected.</para>

            </listitem>

          </itemizedlist>

        </sect2>

<!--
        <sect2 id="s2.ref.menu_cut">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/cut.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Cut</title>

          <indexterm><primary>Cut</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-X</secondary></indexterm>
          <para>Shortcut Ctrl-X.</para>

          <para>This takes the currently selected items, remove them 
          from the diagram, and place them on the clipboard for 
          subsequent pasting.</para>

          <warning>

            <para>In the V0.18 implementation of ArgoUML there are some 
            difficulties with clipboard based functions. This menu 
            option is best avoided.</para>

          </warning>

        </sect2>
-->
<!--
        <sect2 id="s2.ref.menu_copy">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/copy.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Copy</title>

          <indexterm><primary>Copy</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-C</secondary></indexterm>
          <para>Shortcut Ctrl-C.</para>

          <para>This takes the currently selected items and make a copy 
          of them on the clipboard for subsequent pasting.</para>

          <warning>

            <para>In the V0.18 implementation of ArgoUML there are some 
            difficulties with clipboard based functions. This menu 
            option is best avoided.</para>

          </warning>

        </sect2>
-->
<!--
        <sect2 id="s2.ref.menu_paste">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/paste.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Paste</title>

          <indexterm><primary>Paste</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-V</secondary></indexterm>
          <para>Shortcut Ctrl-V.</para>

          <para>This pastes the item(s) last cut or copied to the 
          clipboard on to the current diagram in the drawing 
          pane.</para>

          <warning>

            <para>In the V0.18 implementation of ArgoUML there are some 
            difficulties with clipboard based functions. This menu 
            option is best avoided.</para>

          </warning>

        </sect2>
-->

        <sect2 id="s2.menu_edit_remove_from_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/remove_from_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Remove From Diagram</title>

          <indexterm><primary>Remove From Diagram</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Delete</secondary></indexterm>
          <para>Shortcut Delete.</para>

          <para>This removes the currently selected item(s) from the 
          diagram, but not from the model.</para>

          <para>The modelelement can be re-added to the diagram by 
          button&nbsp;2 click on the modelelement in the explorer, 
          or by dragging it onto the diagram.</para>

        </sect2>

        <sect2 id="s2.menu_edit_delete_from_model">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/delete_from_model.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Delete From Model</title>

          <indexterm><primary>Delete From Model</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>Ctrl-Delete</secondary></indexterm>
          <para>Shortcut Ctrl-Delete.</para>

          <para>This function deletes the selected item(s) from the 
          model completely.</para>

          <para>If the item to be deleted is also present on another 
          diagram than the current one, the dialog box from figure x 
          appears.</para>

          <figure float="1" id="fig.ref.menu_remove_from_model">

            <title>The dialog for confirmation of <literal>Remove from 
            Model</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/confirm_remove.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

		<sect2 id="s2.menu_edit_configure_perspectives">
		
		<title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/nav_config.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>
           Configure Perspectives...</title>
		
		<para>This menu-item invokes the same dialog 
		  as the button at the top of the explorer.
		  See 
          <xref linkend="s1.ref.configure_perspectives"/>.
          for a complete description.</para>
		
		</sect2>

        <sect2 id="s2.ref.menu_settings">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/settings.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Settings...</title>

          <para>This menu entry brings up a dialog box, which allows 
          the user to set various options that control the behavior of 
          ArgoUML (see <xref linkend="fig.ref.menu_settings"/>).</para>
          <para>These settings are saved persistently for use by
          	subsequent ArgoUML sessions.
          </para>
          
          <para>ArgoUML has various user specific configurations that can
          	be set in this dialog box,
          	or directly on the various panes. Also the main window
          	size and location is such a setting. Activating this menu
          	entry causes the information to be saved in the file
          	<literal>argo.user.properties</literal>.
          	The location of this file is in the <literal>.argouml</literal> directory
          	under the &quot;users home directory&quot;, 
          	which is defined as <literal>${user.home}</literal>
          	, and can be determined as described in
          	<xref linkend="s3.ref.menu.environment" />
          	.
          </para>

          <tip>
            <para>This is a text file, which you can edit to configure
            	ArgoUML.
            </para>
          </tip>
          
          <figure float="1" id="fig.ref.menu_settings">

            <title>The dialog for <literal>Settings - 
            Preferences</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_settings.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The options that can be set up on the various tabs are 
          described in the following sections. For each tab there are 
          three buttons at the bottom of the dialog box.</para>

          <itemizedlist>

            <listitem>

              <para><literal>OK</literal>. Activating this button 
              (button&nbsp;1 click) applies the chosen settings and exits 
              the dialog.</para>

            </listitem>

            <listitem>

              <para><literal>Cancel</literal>. Selecting this button 
              (button&nbsp;1 click) exits the dialog without applying any 
              settings changed since the last <literal>Apply</literal> 
              (or since the dialog started if <literal>Apply</literal> 
              has not been used).</para>

            </listitem>

            <listitem>

              <para><literal>Apply</literal>. Selecting this button 
              (button&nbsp;1 click) applies the chosen settings and remains 
              in the dialog.</para>

            </listitem>

          </itemizedlist>

          <para>Closing the dialog (with the close button in the top 
          corner in the border of the window) causes the same effect as 
          <literal>Cancel</literal>.</para>

          <sect3>

            <title>Preferences Tab</title>

            <para>Selecting the <literal>Preferences</literal> tab 
            (button&nbsp;1 click on the tab) gives the following options as 
            check boxes.</para>

            <itemizedlist>

              <listitem>

                <para><literal>Show Splash Panel</literal> (set by 
                default). If enabled ArgoUML will show a small panel 
                with a picture while starting up.</para>

                <tip>

                  <para>The splash panel can be seen by using the Help 
                  menu (see <xref linkend="s2.ref.menu_help_about"/>
                  ).</para>

                </tip>

              </listitem>

              <listitem>

                <para><literal>Reload last saved project on 
                startup</literal> (clear by default). Check this item 
                if you always work on the same project, and wish to 
                load it automatically when you start up ArgoUML.</para>

              </listitem>

              <listitem>

                <para><literal>Strip (non-standard) diagrams 
                from XMI file during import</literal>
                (clear by default). Checking this item will tell
                ArgoUML to ignore the "Diagram" elements when 
                importing XMI files. </para> 
                
                <para>You only need to use this setting, if
                ArgoUML gives an error while importing your
                XMI file saying that it encountered unrecognized
                elements named "Diagram."  Some versions of Poseidon
                are known to create this type of file by default
                although there's usually an export option to
                force them to create standard XMI files.</para>

              </listitem>

<!--              
              <listitem>

                <para><literal>UML Profile file</literal> (
                /org/argouml/model/mdr/mof/default-uml14.xmi 
                by default). </para>
                <para>This is a read-only field which shows the current
                profile being used by ArgoUML.  If you specified an alternate
                profile at startup time or a plugin-module installed a
                different profile, it will display here.</para>
                
                <para>In the future this will be a settable field that
                allows you to select different profiles to match different
                modeling environments (Java, C++, AndroMDA, etc).</para>

              </listitem>
-->
            </itemizedlist>

          </sect3>

          <sect3 id="s3.ref.menu.environment">

            <title>Environment Tab</title>

            <para>Selecting the <literal>Environment</literal> tab 
            (button&nbsp;1 click on the tab) lists several environmental items. 
            Note that none of the paths can be altered &mdash; these are 
            just a matter of record.</para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Environment</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_environment.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <itemizedlist>

              <listitem>

                <para><literal>Default Graphics Format</literal>. 
                Here you can select the same graphics formats as in the 
                menu <xref linkend="s2.ref.menu_export_graphics"/>.
                The chosen format is selected by default 
                in the Export Graphics and Export All Graphics menu-items.
                </para>

              </listitem>

              <listitem>

                <para><literal>Graphics Export Resolution</literal>.
                This allows you to artificially increase 
                the resolution of produced graphics.
                The advised setting is "Standard". 
                To be able to use "High" or "Extra High", 
                you usually need to start the Java virtual machine 
                with extra memory.
                </para>

              </listitem>

              <listitem>

                <para><literal>${argo.ext.dir}</literal>. The directory 
                holding ArgoUML extensions&mdash;by default the <literal>
                ext</literal> sub-directory of the ArgoUML build 
                directory.</para>

              </listitem>

              <listitem>

                <para><literal>${java.home}</literal>. The home 
                directory of the Java Runtime Environment (JRE).</para>

              </listitem>

              <listitem>

                <para><literal>${user.home}</literal>. The user&apos;s 
                home directory. Used for storing the <literal>
                argo.user.properties</literal> file, under the
                <literal>.argouml</literal> directory.</para>

              </listitem>

              <listitem>

                <para><literal>${user.dir}</literal>. The directory 
                from which ArgoUML was started.</para>

              </listitem>

              <listitem>

                <para><literal>Startup Directory</literal>. The 
                directory in which ArgoUML starts file searches 
                etc.</para>

              </listitem>

            </itemizedlist>

          </sect3>

          <sect3>

            <title>User Tab</title>

            <para>This tab allows the user to record additional 
            information of use to the system. There are two text boxes 
            provided.</para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              User</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_user.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <itemizedlist>

              <listitem>

                <para><literal>Full Name</literal>. Allows the user to 
                record her full name.</para>

              </listitem>

              <listitem>

                <para><literal>Email Address</literal>. Allows the 
                user to record his Email address.</para>

              </listitem>

            </itemizedlist>

            <para>This information is used when requesting to-do help 
            by Email.</para>

          </sect3>

          <sect3 id="s3.ref.menu_settings_appearance">

            <title>Appearance Tab</title>

            <para>This tab allows the user to specify the LAF (Look And 
            Feel) and theme, i.e. what the complete ArgoUML UI looks 
            like. It comprises the following settings.</para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Appearance</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_appearance.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <itemizedlist>

              <listitem>

                <para><literal>Look and Feel</literal>. The choice made 
                here influences the complete User Interface. It only 
                becomes effective when ArgoUML is exited and 
                restarted.</para>

              </listitem>

              <listitem>

                <para><literal>Metal Theme</literal>. This item is 
                downlighted if the Metal LAF is not chosen. The choice 
                made here influences the complete User Interface. It 
                only becomes effective when ArgoUML is exited and 
                restarted.</para>

              </listitem>

              <listitem>

                <para><literal>Smooth edges of diagram lines and 
                text</literal>. This feature is known as 
                <quote>anti-aliasing</quote> on certain platforms. It 
                causes diagonal lines to look much less jagged, by 
                making use of several shades of gray. This feature only 
                works if the operating system supports it.</para>

              </listitem>

            </itemizedlist>

          </sect3>

          <sect3 id="s3.ref.menu_settings_profiles">

            <title>Profiles Tab</title>

            <para>In this tab the user may configure the ArgoUML application
	    settings related to the profiles.</para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Profiles</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_profiles.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <itemizedlist>

              <listitem>
              <para><literal>Stereotype Visualization</literal> &ndash; select
              to view stereotypes as text, small or big icons.</para>
              </listitem>

              <listitem>
              <para><literal>Default XMI directories</literal> &ndash; allows
		the user to configure directories where ArgoUML can find the
	        user defined profiles.</para>
              </listitem>

              <listitem>
              <para><literal>Default Profiles</literal> &ndash; select which 
	      profiles from the available profiles are configured in new
	      projects by default.</para>
              </listitem>

            </itemizedlist>

          </sect3>

          <sect3 id="s3.ref.menu_settings_configure_shortcuts">
            <title>Configure Shortcuts Tab</title>
            <para>(To Be Written)</para>
            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Configure Shortcuts</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_configure_shortcuts.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

          </sect3>

          <sect3 id="s3.ref.menu_settings_notations">

            <title>Notation Tab</title>

            <para>This tab allows the user to specify certain notation 
            settings, i.e. how things are shown on diagrams. It 
            comprises the following check boxes.</para>
            
            <para>All settings here, only define the defaults used for new projects.
            If you want to change the way 
            the diagrams in your current project look, 
            then see the File - Properties menu.</para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Notations</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_notations.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <itemizedlist>

              <listitem>

                <para><literal>Notation Language</literal> (
                UML 1.4
                by default). This feature allows changing the default notation 
                (i.e. language: UML, Java,...) used on the diagrams 
                for new projects. 
                Suppose that a designer indicates that the 
                default notation of a project is Java.
                When he saves the project, 
                the choice for Java is stored inside the project file.
                If someone else is viewing the 
                diagram, he will see the Java notation, too.
                This person can select the UML notation in the 
                File - Notation menu, and see all diagrams in UML language.
                See
                <xref linkend="s2.ref.menu_notation"/>).</para>

              </listitem>

              <listitem>

                <para><literal>Show name of nodes in bold font</literal>.</para>

                <para>This feature causes the names of every node (i.e. something drawn with a closed polygon) to be bold.</para>
                
                <para>There is no semantics to showing bold names, but it may make your diagrams look nicer.</para>

              </listitem>

              <listitem>

                <para><literal>Use guillemots</literal> (&laquo;&nbsp;&raquo;) for 
                stereotypes (clear by default). By default ArgoUML uses 
                pairs of <emphasis>less than</emphasis> and 
                <emphasis>greater than</emphasis> (&lt;&lt; &gt;&gt;) 
                characters for stereotypes. If this box is checked 
                stereotypes on diagrams are shown between true 
                guillemots (&laquo;&nbsp;&raquo;).</para>

                <para>This feature is presumably added to ArgoUML 
                because guillemots are poorly supported by various 
                fonts, and if they are present, then they are quite 
                small and poorly visible.</para>
                
                <para>Independent of the way they are shown, 
                when entering stereotypes, you can always type
                real guillemots (if your keyboard supports it)
                or their &lt;&lt; &gt;&gt; equivalents.</para>

              </listitem>

              <listitem>

                <para><literal>Show association names</literal>.</para>

                <para>This feature causes the names of every association to be hidden 
                if not marked.</para>

              </listitem>

              <listitem>

                <para><literal>Show visibility</literal> (clear by 
                default). If this is selected, then ArgoUML will
                show the visibility indicators in front of e.g. attributes
                in the diagram.
                In UML the notation is "+" for public, "-" for private,
                "#" for protected, and "~" for package. 
                E.g. for an attribute, it may show:
                <literal>+newAttr : int</literal>.
                </para>

              </listitem>

              <listitem>

                <para><literal>Show multiplicity</literal> (clear by 
                default). If this is selected, then ArgoUML will show 
                the multiplicity of e.g. attributes in the diagram. 
                In UML notation, the multiplicity is shown between [], such as: 
                <literal>+newAttr [0..*] : int</literal>.
                This setting has no impact on showing multiplicity 
                near associationends.
                </para>

              </listitem>

              <listitem>

                <para><literal>Show initial value</literal> (clear by 
                default). If this is selected, then ArgoUML will show
                the initial value of e.g. attributes in the diagram.
                In UML notation, the initial value is shown e.g. like this:
                <literal>+newAttr : int = 1</literal>.
              </para>

              </listitem>

              <listitem>

                <para><literal>Show properties</literal> (clear by 
                default). If this is selected, then ArgoUML will show
                various properties between braces {}.
                E.g. for an attribute, it may show:
                <literal>+newAttr : int { frozen }</literal>.
                </para>

              </listitem>

              <listitem>

                <para><literal>Show types and parameters</literal> 
                (set by default). When this checkbox is unmarked, 
                attributes in classes are shown without type indication, 
                and operations are shown without parameters.
                This feature may be usefull during 
                the analysis phase of your project.
                If all checkmarks in 
                the Notation Tab are unchecked, then
                e.g. for an attribute, ArgoUML may show:
                <literal>newAttr</literal>. And for an operation: 
                <literal>newOperation()</literal>.
                </para>

              </listitem>

              <listitem>

                <para><literal>Show stereotypes in explorer</literal> 
                (clear by default). If this is selected, then ArgoUML will show
                stereotypes next to the icons of the modelelements 
                in the Explorer, i.e. the tree structure at the left hand side.
                </para>

              </listitem>

              <listitem>

                <para><literal>Show "1" multiplicities</literal>.</para>

                <para>This feature allows the user to select if he wants 
                to show all multiplicities that are "1" to be shown or not..</para>
                
                <para>Some people consider not showing 
                the multiplicity as "undefined".
                So, the only way to differentiate between 
                a multiplicity of 1 and an undefined multiplicity, 
                is to mark this checkbox.</para>

              </listitem>

              <listitem>

                <para><literal>Hide arrowheads for bi-directional associations.</literal>.</para>

                <para>The UML standard defines different ways 
                to indicate navigability of an association on diagrams. 
                Presentation option 1 is to show all arrows 
                (i.e. you can only navigate in a certain direction if an arrow is drawn), 
                presentation option 2 is to show no arrows at all, 
                and presentation option 3 is to show only an arrow
                if the association is unidirectional.</para>
                
                <para>Before the release of version 0.26, 
                ArgoUML could only use presentation option 3. 
                Currently, the user can choose between option 1 and 3. 
                <!-- This is introduced thanks to issue 535. -->
                Option 2 is not supported.</para>

                <para>In the past, option 3 was used most often in other UML tools, 
                but nowadays option 1 is more common.</para>

              </listitem>

              <listitem>

                <para><literal>Default shadow width</literal> (set to 1 
                by default). ArgoUML is able to draw all elements 
                on a diagram with a shadow. Use this setting to adjust the 
                size of the shadow, used when the modelelement is created.
                The details tab "Presentation" allows to set the shadow per
                modelelement, after they are created.
                </para>

              </listitem>

            </itemizedlist>

          </sect3>


          <sect3 id="s3.ref.menu_settings_diagram_appearance">
            <title>Diagram Appearance Tab</title>
            <para>(To Be Written)</para>
            <figure float="1">

              <title>The dialog for <literal>Settings - 
              Diagram Appearance</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_diagram_appearance.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

          </sect3>


          <sect3 id="s3.ref.menu_settings_modules">

            <title>Modules Tab</title>

            <para>This tab shows a list of modules that are installed, 
            which may be enabled or disabled. Since this is a new 
            concept for ArgoUML, it currently contains a list of modules that 
            can not be removed, and a button to test the concept. 
            Pressing this button adds a useless menu-item
            on the Tools menu, nothing else.</para>

            <para>Notice also that this is a &quot;new&quot; modules 
            concept so the old Pluggable modules do not work this way, 
            and are not listed.</para>

          </sect3>

          <sect3 id="s3.ref.menu_settings_plugins">

            <title>Extra Tabs added by Plugins</title>

            <para>A plug-in module has the possibility to add 
            extra tabs. 
            One example is C++; it adds the following tab.
            </para>

            <figure float="1">

              <title>The dialog for <literal>Settings - 
              C++</literal>.</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/menu_settings_cpp.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

          </sect3>

        </sect2>

      </sect1>

      <sect1>

        <title>The View Menu</title>

        <para>This menu is used for actions that affect how the various 
        panes are viewed.</para>

        <sect2>

          <title>Goto Diagram...</title>

          <para>This menu entry brings up a dialog box, describing all 
          the diagrams in the current project under ArgoUML.</para>

          <figure float="1" id="fig.ref.menu_goto_diagram">

            <title>The dialog for <literal>Goto 
            Diagram...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_goto_diagram.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The dialog box contains a table with three columns and 
          one row for each diagram in the current project. A scroll bar 
          gives access if the table is too long for the box. Double 
          button&nbsp;1 click on any row will select that diagram in the 
          editing pane. The three columns are as follows.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Type</literal>. Lists the type of 
              diagram.</para>

            </listitem>

            <listitem>

              <para><literal>Name</literal>. Lists the name given to 
              the diagram.</para>

            </listitem>

            <listitem>

              <para><literal>Description</literal>. Shows how many 
              nodes and edges there are on the diagrams. A node is a 
              <quote>2-D</quote> model element and an edge is a connector 
              model element.</para>

            </listitem>

          </itemizedlist>

          <para>This dialog box is not modal, which allows it to remain 
          open while editing the model for easy navigation.</para>

          <warning>

            <para>The V0.26 implementation of ArgoUML does not 
            immediately update the dialog box with changes made to 
            diagrams: change of name, addition of diagrams, deletion of 
            diagrams.<!-- This is issue 2475. -->
            </para>

          </warning>

        </sect2>

        <sect2 id="s2.ref.menu_find">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/find.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Find...</title>

          <para>This menu entry brings up a non-modal dialog box for 
          the ArgoUML search engine.</para>

          <figure float="1" id="fig.ref.menu_find">

            <title>The dialog for <literal>Find...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_find.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <!--para>At the top, the dialog box has four tabs labelled 
          <literal>Name and Location</literal>, <literal>
          Last Modified</literal>, <literal>Tagged Values</literal> and 
          <literal>Constraints</literal>. Of these all but the first 
          are grayed out in the V0.22 version of ArgoUML (because they
          are not implemented yet), so the first tab is always 
          selected.</para-->
          <!-- This is issue 2501 -->

          <para>The <literal>Name and Location</literal> specifies the 
          search to be made. It contains the following:</para>

          <itemizedlist>

            <listitem>

              <para>A text box labeled <literal>Element Name:</literal> 
              specifies the name of the model element to search 
              for. Wild cards (<literal>*</literal>, <literal>
              ?</literal>) may be used here. A drop down gives access 
              to find expressions previously used.</para>

            </listitem>

            <listitem>

              <para>A text box labeled <literal>In Diagram:</literal> 
              specifies which diagrams are to be searched. Again wild 
              cards may be used. Both these two text boxes have a 
              default entry of <literal>*</literal>, i.e. match 
              anything.</para>

            </listitem>

            <listitem>

              <para>To the right of these two text boxes, a selector 
              labeled <literal>Element Type:</literal> allows you to 
              specify the UML metaclass for which you are 
              searching.</para>

            </listitem>

            <listitem>

              <para>A selector labeled <literal>Find in:</literal> 
              allows the search to be made over the entire project (the 
              default) or as a sub-search over the results of a 
              previous search. When opened, a list of all the search 
              result tabs appears.</para>

            </listitem>

            <listitem>

              <para>Beneath these boxes is the button <literal>Clear 
              Tabs</literal>. This clears the display of tabs with the 
              results from previous searches (see below). This button 
              is downlighted if there are no tabs but the <literal>
              Help</literal> tab.</para>

            </listitem>

            <listitem>

              <para>And finally, there is the button <literal>
              Find</literal>. This causes the search specified in the 
              text boxes and selectors above to be executed. The 
              results are displayed in a tab taking up the lower two 
              thirds of the page.</para>

            </listitem>

          </itemizedlist>

          <para>The lower two thirds of the dialog comprises an initial 
          tab (labeled <literal>Help</literal>) giving summary help, 
          and further tabs displaying the results of searches. These 
          search tabs are labeled with a summary of the search 
          <emphasis>element</emphasis> 
          <literal>in</literal> <emphasis>diagram</emphasis> and are 
          divided horizontally in two halves.</para>

          <para>Button&nbsp;1 double clicking on these tabs removes the tab, 
          and spawns a new window that contains the tab contents, i.e. 
          the search results. This window can be moved and sized at 
          will. This does not work for the help tab.</para>

          <para>The top half is labeled <literal>Search 
          Results:</literal> followed by a count of the number of items 
          found. It comprises a table with one row for each
          model element and four columns. The width of the columns can be 
          adjusted.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Type</literal>. Lists the type of
              model element.</para>

            </listitem>

            <listitem>

              <para><literal>Name</literal>. Lists the name given to 
              the model element.</para>

            </listitem>

            <listitem>

              <para><literal>In Diagram</literal>. Where the model element 
              is visible on a diagram, this lists the name of the 
              diagram, otherwise it shows <literal>N/A</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>Description</literal>. Contains a 
              description of the model element. In ArgoUML V0.18 
              this seems to be restricted to the single entry <literal>
              docs</literal>.</para>

            </listitem>

          </itemizedlist>

          <para>Button&nbsp;1 click on any row will give more information on 
          that model element by showing related model elements in the bottom half 
          (see below). Double click on any row describing a model element 
          on a diagram and that item and diagram will be 
          selected.</para>

          <para>The bottom half of the tab is a table labeled <literal>
          Related Elements:</literal> and is a table with the same 
          columns as the top half. When a model element has been 
          selected in the top half, this table shows the details of any 
          related elements.</para>

          <tip>

            <para>Enlarging the dialog vertically shows that the 
            &quot;Related Items&quot; part changes in size, but not the 
            Search results part. However, between them is a divider 
            line and when hovering over this line, the mouse pointer 
            changes into a sizing icon, and the border between these 2 
            areas can be moved up or down to redistribute the space in 
            the window.</para>

          </tip>

          <warning>

            <para>This dialog box is not modal, which allows it to 
            remain open while editing the model for easy navigation. 
            But the V0.26 implementation of ArgoUML does not immediately 
            update the dialog box with changes made to the found 
            model elements: change of model element name, change of diagram name. 
            Deletion of a diagram does not stop the possibility to 
            navigate to it.
            <!-- This is issue 4376. -->
            </para>

          </warning>

        </sect2>

        <sect2 id="s2.ref.menu_zoom">

          <title>Zoom</title>

          <para>This entry brings up a sub-entry, which allows scaling 
          the view of all diagrams to a factor of its normal size. This 
          setting is not saved persistently.</para>

          <para>The sub-menu items that can be selected are:</para>

          <itemizedlist>

            <listitem>

              <para><literal>Zoom Out</literal>. Shortcut (Ctrl-Minus). 
              Gives more overview over the drawing.</para>

            </listitem>

            <listitem>

              <para><literal>Zoom Reset</literal>. Returns to the 
              default zoom ratio (i.e. 100%).</para>

            </listitem>

            <listitem>

              <para><literal>Zoom In</literal>. Shortcut (Ctrl-Plus). 
              Makes the items on the drawings bigger.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="s2.ref.menu_adjust_grid">

          <title>Adjust Grid</title>

          <para>This allows selection of the grid representation on the screen 
          between the following:</para>

          <itemizedlist>

            <listitem>

              <para><literal>Lines 16</literal>: 
              full grid at 16 pixel spacing. </para>

            </listitem>

            <listitem>

              <para><literal>Lines 8</literal>:
              full grid at 8 pixel spacing.</para>

            </listitem>

            <listitem>

              <para><literal>Dots 16</literal>:
              dots at 16 pixel spacing (the default).</para>

            </listitem>

            <listitem>

              <para><literal>Dots 32</literal>:
              dots at 32 pixel spacing.</para>

            </listitem>

            <listitem>

              <para><literal>None</literal>:
              no grid of any form.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="s2.ref.menu_grid_snap">

          <title>Adjust Snap</title>

          <para>This allows selection of the spacing of grid snapping
          between the following:</para>

          <itemizedlist>

            <listitem>

              <para><literal>Snap 4</literal>:
              snap at 4 pixel spacing.</para>

            </listitem>

            <listitem>

              <para><literal>Snap 8</literal>:
              snap at 8 pixel spacing (the default).</para>

            </listitem>

            <listitem>

              <para><literal>Snap 16</literal>:
              snap at 16 pixel spacing.</para>

            </listitem>

            <listitem>

              <para><literal>Snap 32</literal>:
              snap at 32 pixel spacing.</para>

            </listitem>

          </itemizedlist>

          <note>

            <para>There is no option to turn off snap to grid 
            altogether</para>

          </note>

          <note>

            <para>If you wish to align existing elements to changed
            snap boundaries, 
            you can use the <literal>
            Arrange &gt; Align To Grid Snap</literal> menu (see 
            <xref linkend="s2.ref.menu_align"/>).</para>

          </note>

        </sect2>

        <sect2>

          <title>Page Breaks</title>

          <para>This toggles whether page breaks are shown on the 
          diagram (as white dotted lines).</para>

          <warning>
            <para>This menu item does not work in ArgoUML V0.26.</para>
            <!-- This menu-item is incorrectly implemented in the 
            V0.22 version of ArgoUML, since it should be a tick box 
            toggle.  This is issue  604.
            Also, the lines are reported to be incorrect 
            regarding the chosen paper format and orientation.
            This is issue 1874. 
            And the lines are reported not visible at all in ArgoUML V0.24.
            This is mentioned in issue 604 and in issue 1874. 
            -->
          </warning>

        </sect2>
        
        <sect2>
          <title>Toolbars</title>
          <para>This menu allows the user to hide or show any of the bars at will. 
            By default, all of them are shown.</para>
        </sect2>

        <sect2>

        	<title>XML Dump</title>

        	<para>
        		This activates a window that shows the complete contents 
        		of the current project in XML format. 
        	</para>

        	<para>Although very useful for debugging ArgoUML, 
        	this menu function is hardly interesting to the common user.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.create.diagram.menu">

        <title>The Create Menu</title>

        <para>This menu provides for creating the various types of UML 
        diagrams supported by ArgoUML.</para>

        <sect2 id="s2.ref.create.diagram.use_case_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/use_case_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Use Case Diagram</title>

          <para>This menu entry creates a blank use case diagram, and 
          selects that diagram in the editing pane. If a package is 
          currently selected, then the use case diagram will be created 
          within that package. 
          This means that it will be shown within the package on 
          the explorer hierarchy (under Package-centric view) and 
          model elements created on the diagram will be created within the 
          namespace of the package. This does not only apply to a 
          package, but also to a class, interface, use case, etc.</para>

          <tip>

            <para>This does not prevent model elements from other 
            namespaces/packages appearing on the diagram. They can be 
            added from the explorer using <literal>Add to 
            Diagram</literal> from the button&nbsp;2 pop-up menu.</para>

          </tip>

        </sect2>

        <sect2 id="s2.ref.create.diagram.class_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/class_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Class Diagram</title>

          <para>This menu entry creates a blank class diagram, and 
          selects that diagram in the editing pane. If a package is 
          currently selected, the class diagram will be created within 
          that package. 
          This means that it will be shown within the package on the 
          explorer hierarchy (under Package-centric view) and model elements 
          created on the diagram will be created within the namespace 
          of the package. This does not only apply to a package, but 
          also to a class, interface, use case, etc.</para>

          <tip>

            <para>This does not prevent model elements from other 
            namespaces/packages appearing on the diagram. They can be 
            added from the explorer using <literal>Add to 
            Diagram</literal> from the button&nbsp;2 pop-up menu.</para>

          </tip>

        </sect2>

        <sect2 id="s2.ref.create.diagram.sequence_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/sequence_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Sequence Diagram</title>

          <para>This menu entry creates a blank sequence diagram, and 
          selects that diagram in the editing pane. 
          It also creates a <literal>
          Collaboration</literal> UML element, 
          which is a container for the elements shown on the new diagram.
          If a class is 
          currently selected, a sequence diagram and a collaboration
          will be created
          that represent the behaviour of that class. 
          This means that the created elements 
          will be shown within the class in the 
          explorer hierarchy (under Package-centric view) and model elements 
          created on the diagram will be created within the namespace 
          of the collaboration. A sequence diagram may 
          not only represent the behavior of a class, but 
          also of any other classifier, such as interface, use case, etc.
          It is also possible to make sequence diagrams for an operation.
          </para>

        </sect2>

        <sect2 id="s2.ref.create.diagram.collaboration_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/collaboration_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Collaboration Diagram</title>

          <para>This menu entry creates a blank collaboration diagram, 
          and selects that diagram. 
          It also creates a <literal>
          Collaboration</literal> UML element, 
          which is a container for the elements shown on the new diagram.
          If a 
          package is selected when this menu item is activated, 
          the collaboration diagram will 
          be created within a collaboration within that package.
          This means that it 
          will be shown within the collaboration within the package on 
          the explorer hierarchy (under Package-centric view) and 
          model elements created on the diagram will be created within the 
          namespace of the collaboration within the package.</para>

          <tip>

            <para>This does not prevent model elements from other 
            namespaces/packages appearing on the diagram. They can 
            added from the explorer by 
            dragging or by 
            using <literal>Add to Diagram</literal> 
            from the button&nbsp;2 pop-up menu.</para>

          </tip>

        </sect2>

        <sect2 id="s2.ref.create.diagram.state_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/state_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Statechart Diagram</title>

          <para>This menu entry creates a blank statechart diagram 
          associated with the currently selected class, and selects 
          that diagram in the editing pane. 
          It also creates a <literal>
          Statemachine</literal> UML element, 
          which is a container for the elements shown on the new diagram.
          </para>

          <para>Statechart diagrams are
            associated with a model element capable of dynamic behavior, such as
            a classifier or a behavioral feature, 
            which provides the context for the
            state machine it represents. 
            Suitable model elements are e.g. a class,
            an operation, and a use case. 
            If such element is not selected at the time the
           <literal>New Statechart Diagram</literal> 
            menu is activated,
            then an unattached  
            statemachine is created.
            To obtain a well-formed UML model, 
            you have to set the context of the statemachine 
            on its details pane.
            </para>

        </sect2>

        <sect2 id="s2.ref.create.diagram.activity_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/activity_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Activity Diagram</title>

          <para>This menu entry creates a blank activity diagram 
          associated with the currently selected class, and selects 
          that diagram in the editing pane. 
          It also creates a <literal>
          ActivityGraph</literal> UML element, 
          which is a container for the elements shown on the new diagram.
          </para>

          <para>Activity diagrams are 
            associated with a model element capable of dynamic behavior, such as
            packages, classifiers (including use cases) 
            and behavioral features. Suitable model elements are e.g. a 
            class, a use case, an operation, and a package. 
            If such element is not selected at the time the
           <literal>New Activity Diagram</literal> 
            menu is activated,
            then an unattached  
            ActivityGraph is created.
            To obtain a well-formed UML model, 
            you have to set the context of the ActivityGraph 
            on its details pane.
          </para>

        </sect2>

        <sect2 id="s2.ref.create.diagram.deployment_diagram">

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/deployment_diagram.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          New Deployment Diagram</title>

          <para>This menu entry creates a blank deployment diagram, and 
          selects that diagram in the editing pane. 
          <!--If a package is 
          currently selected, the deployment diagram will be created 
          within that package, it will be shown within the package on 
          the explorer hierarchy (under Package-centric view) and 
          model elements created on the diagram will be created within the 
          namespace of the package.-->
          </para>

          <tip>

            <para>Model elements from other 
            namespaces/packages can be
            added from the explorer by
            dragging or by
            using <literal>Add to Diagram</literal> 
            from the button&nbsp;2 pop-up menu.</para>

          </tip>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.menu_arrange">

        <title>The Arrange Menu</title>

        <para>This menu provides a range of functions to help in the 
        alignment of model elements on diagrams within the editing pane. In 
        general the menu function invoked is applied to any model element or 
        model elements currently selected in the editing pane.</para>

        <sect2 id="s2.ref.menu_align">

          <title>Align</title>

          <para>This sub-menu aligns the selected items. There are 
          seven alignment options provided.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_tops.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Tops</literal>. Aligns the selected 
              model elements by their top edges.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_bottoms.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Bottoms</literal>. Aligns the selected 
              model elements by their bottom edges.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_rights.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Rights</literal> (Shortcut Ctrl-R). Aligns 
              the selected model elements by their right edges.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_lefts.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Lefts</literal> (Shortcut Ctrl-L). Aligns 
              the selected model elements by their left edges.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_horizontal_centers.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Horizontal Centers</literal>. Aligns the 
              selected model elements so their horizontal centers are in a 
              vertical line.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_vertical_centers.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align Vertical Centers</literal>. Aligns the 
              selected model elements so their vertical centers are in a 
              horizontal line.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/align_to_grid.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Align To Grid</literal>. Aligns the selected 
              model elements so their top and right edges are on the grid 
              snap boundary (see <xref linkend="s2.ref.menu_grid_snap"/>
              ) edge.</para>

              <tip>

                <para>The alignment is to the current <emphasis>grid 
                snap</emphasis> setting, which may be smaller, larger 
                or the same as the displayed grid. Since items are 
                aligned to the grid snap boundary any way when you 
                place them, this menu entry has no effect unless you 
                have either changed the grid snap to a larger value or 
                used one of the other <literal>Arrange</literal> menu 
                entries to push items off their initial 
                positions.</para>

              </tip>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Distribute</title>

          <para>This sub-menu distributes the selected items. There are 
          four distribution options provided.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/distribute_horizontal_spacing.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Distribute Horizontal Spacing</literal>. The 
              leftmost and rightmost selected model elements are not moved. 
              The others are adjusted horizontally until the horizontal 
              space (i.e. from the right edge of the left model element to 
              the left edge of the right model element) is the same for all 
              of the selected items</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/distribute_horizontal_centers.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Distribute Horizontal Centers</literal>. The 
              leftmost and rightmost selected model elements are not moved. 
              The others are adjusted horizontally until the distance 
              between the horizontal centers of all the selected items 
              is the same.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/distribute_vertical_spacing.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Distribute Vertical Spacing</literal>. The top 
              and bottom selected model elements are not moved. The others 
              are adjusted vertically until the vertical space (i.e. 
              from the bottom edge of the top model element to the top edge 
              of the bottom model element) is the same for all of the 
              selected items</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/distribute_vertical_centers.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Distribute Vertical Centers</literal>. The top 
              and bottom selected model elements are not moved. The others 
              are adjusted vertically until the distance between the 
              vertical centers of all the selected items is the 
              same.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="s2.ref.menu_reorder">

          <title>Reorder</title>

          <para>This sub-menu adjusts the ordering of overlapping 
          items. There are four reorder options provided.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/forward.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Forward</literal>. The selected model elements are 
              moved one step forward in the ordering hierarchy with 
              respect to other model elements they overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/backward.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Backward</literal>. The selected model elements are 
              moved one step back in the ordering hierarchy with 
              respect to other model elements they overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/to_front.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>To Front</literal>. The selected model elements are 
              moved to the front of any other model elements they 
              overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/to_back.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>To Back</literal>. The selected model elements are 
              moved to the back of any other model elements they 
              overlap.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Size To Fit Contents</title>

          <para>This menu-item acts on all selected items on the 
          current diagram. It resets all sizes of all model elements to its 
          minimum size for 
          which all text fits inside.</para>

        </sect2>

        <!--sect2>

          <title>Toggle Auto Resizing</title>

          <para>This menu-item is a checkbox 
          that currently does not do anything.
          </para>

        </sect2-->

        <sect2>

          <title>Layout</title>

          <para>This menu-item provides an automatic diagram layout 
          function, i.e. when activating this menu-item, all items on 
          the current class diagram are rearranged according a certain 
          layout algorithm.</para>

          <para>This function currently only works for classdiagrams. 
          For all other types of diagrams, the menu-item
          does not do anything 
          <!--(it should be downlighted)-->.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>The Generation Menu</title>

        <para>This menu provides support for code generation from UML 
        diagrams. The functionality is built around the structural 
        information of class diagrams.</para>

        <note>

          <para>Without any plugin modules installed, ArgoUML supports 
          only code generation of Java. ArgoUML V0.20 supports the 
          following languages by plugin: C#, C++, php4, php5.</para>

        </note>

        <warning>

          <para>Code generation is still very much a work in progress. 
          The current version of ArgoUML will generate a structural 
          template for your code, but is not able to handle behavioral 
          specifications to generate code for the dynamic behavior of 
          the model.</para>

        </warning>

        <sect2 id="s2.ref.menu_generate_selected_classes">

          <title>Generate Selected Classes ...</title>

          <para>This menu entry brings up a dialog box for the ArgoUML 
          code generator (see 
          <xref linkend="fig.ref.menu_generate_selected_classes"/>
          ).</para>

          <figure float="1" id="fig.ref.menu_generate_selected_classes">

            <title>The dialog for <literal>Generate Selected 
            Classes...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_generate_dialog.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>Below a label <literal>Available Classes</literal> the 
          dialog box lists each of the selected classes by name with a 
          check box to the left, for each language installed. All the 
          checkboxes are initially unchecked. Checking any of these 
          boxes will cause code generation for that class. Checking 
          multiple languages for a class causes it to be generated in 
          all these languages.</para>

          <para>The buttons <literal>Select All</literal> and <literal>
          Select None</literal> may help when a lot of items have to be 
          selected or deselected.</para>

          <para>In the lower portion of the dialog box is an editable 
          combo box labeled <literal>Output Directory</literal> to 
          specify the directory in which code is generated. Within this 
          directory, a top level directory will be created with the 
          name of the model. Further sub-directories will be created to 
          reflect the package/namespace hierarchy of the model. A drop 
          down selector gives access to previously selected output 
          directories.</para>

          <para>Finally, at the bottom of the dialog box are two 
          buttons, labeled <literal>Generate</literal> and <literal>
          Cancel</literal>. Button&nbsp;1 click on the former will cause the 
          code to be generated, button&nbsp;1 click on the latter will 
          cancel code generation.</para>

        </sect2>

        <sect2>

          <title>Generate All Classes...</title>

          <indexterm><primary>Generate All Classes</primary></indexterm>
          <indexterm><primary>Shortcut 
          key</primary><secondary>F7</secondary></indexterm>
          <para>Shortcut F7.</para>

          <para>This function behaves as <literal>
          Generate Selected Classes...</literal> (see 
          <xref linkend="s2.ref.menu_generate_selected_classes"/>) 
          would with all classes in the current diagram selected.</para>

        </sect2>

        <sect2>

          <title>Generate Code for Project... (To be Written)</title>

          <para />

        </sect2>

        <sect2>

          <title>Settings for Generate for Project... (To be 
          Written)</title>

          <para />

        </sect2>

      </sect1>

      <sect1 id="s1.ref.menu_critique">

        <title>The Critique Menu</title>

        <para>This menu controls one of ArgoUML&apos;s unique 
        features&mdash;the use of critics to guide the designer. The theory 
        behind this is well described in Jason Robbins&apos; PhD 
        dissertation 
        <ulink url="http://argouml.tigris.org/docs/robbins_dissertation/">
        http://argouml.tigris.org/docs/robbins_dissertation/</ulink>.</para>

        <note>

          <para>A word about terminology: The 
          <emphasis>critics</emphasis> are background processes, which 
          evaluate the current model according to various 
          <quote>good</quote> design criteria. There is one critic for 
          every design criterion.</para>

          <para>The output of a critic is a 
          <emphasis>critique</emphasis>&mdash;a statement about some aspect 
          of the model that does not appear to follow good design 
          practice.</para>

          <para>Finally a critique will generally suggest how the bad 
          design issue it has identified can be rectified, by raising a 
          <emphasis>to-do item</emphasis>.</para>

        </note>

        <note>

          <para>The critics run as asynchronous processes in parallel 
          with the main ArgoUML tool. Changes typically take a second 
          or two to propagate as the critics wake up.</para>

        </note>

        <sect2>

          <title>Toggle Auto-Critique</title>

          <para>This is a check box, controlling whether the critics 
          are running. By default it is checked. If unchecked, then all 
          critics are disabled, and any to-do items generated by 
          critics (the only others being those the designer has added 
          by hand) are hidden in the to-do pane.</para>

        </sect2>

        <sect2 id="s2.ref.menu_design_issues">

          <title>Design Issues...</title>

          <para>This menu entry brings up a dialog box controlling how 
          critics associated with a particular design area are to be 
          handled (see <xref linkend="fig.ref.menu_design_issues"/>
          ).</para>

          <figure float="1" id="fig.ref.menu_design_issues">

            <title>The dialog for <literal>
            Design Issues...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_design_issues.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>ArgoUML categorizes critics according the the design 
          issue they address. There are 16 such categories. The critics 
          in each category are discussed in detail in the chapter on 
          critics (<xref linkend="ch.ref.critics"/>).</para>

          <para>The sliders may be set for each category to control the 
          critics that trigger for that category. Setting a slider to 
          <literal>Off</literal> will disable all critics in that 
          category, and remove all associated to-do items from the 
          to-do pane.</para>

          <para>Setting a slider to a higher priority value will enable 
          all critics at or above that priority level within the design 
          issue category (<literal>Off</literal> being the lowest 
          priority).</para>

          <note>

            <para>The sliders are set by default to <literal>
            High</literal> for all design categories.</para>

          </note>

        </sect2>

        <sect2>

          <title>Design Goals...</title>

          <para>This menu entry brings up a dialog box controlling how 
          design goals are to be handled (see 
          <xref linkend="fig.ref.menu_design_goals"/>).</para>

          <figure float="1" id="fig.ref.menu_design_goals">

            <title>The dialog for <literal>
            Design Goals...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_design_goals.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>ArgoUML has the concept that the designer will have a 
          number of design goals to be achieved (for example good 
          structural representation, detailed behavioral representation 
          etc). Critics are associated with one or more goals.</para>

          <para>This dialog allows the user to specify the priority of 
          each design goal.</para>

          <para>The sliders may be set for each design goal to control 
          the critics that trigger for that goal. Setting a slider to 
          zero will disable all critics in that goal, and remove all 
          associated to-do items from the to-do pane.</para>

          <para>Setting a slider to a higher value will enable all 
          critics at or above that priority level within the design 
          issue category (1 being the highest priority and 5 the 
          lowest).</para>

          <tip>

            <para>It may be useful to think of this function as very 
            similar to <literal>Design Issues...</literal> (see 
            <xref linkend="s2.ref.menu_design_issues"/>), but with 
            grouping of critics according to the outcomes of OOA&amp;D 
            rather than grouping according to the structure of 
            UML.</para>

          </tip>

          <warning>

            <para>The V0.20 version of ArgoUML provides a single design 
            goal, <literal>Unspecified</literal>, with its slider set 
            by default to priority 1. However it contains no critics 
            and so has no effect.</para>

          </warning>

        </sect2>

        <sect2 id="s2.ref.menu_browse_critics">

          <title>Browse Critics...</title>

          <para>This menu entry brings up a dialog box controlling the 
          individual critics (see 
          <xref linkend="fig.ref.menu_browse_critics"/>).</para>

          <figure float="1" id="fig.ref.menu_browse_critics">

            <title>The dialog for <literal>
            Browse Critics...</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_browse_critics.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>This dialog controls the behavior of individual 
          critics. To the left is a list of all the critics, to enable 
          them to be switched on or off individually. For each critic 
          there are three columns, labeled <literal>Active</literal>, 
          <literal>Headline</literal> and <literal>Snoozed</literal>. 
          The first of these is a check box, which may be toggled with 
          button&nbsp;1 click. The second is the headline name of the 
          critic, the third indicates if the critic has been snoozed 
          from the to-do pane (see <xref linkend="ch.ref.todopane"/>. A 
          critic is only really active if the box in the first column 
          is checked <emphasis>and</emphasis> the critic has not been 
          snoozed.</para>

          <para>Any critic for which the box in the first column is 
          unchecked is inactive and will not trigger. In addition any 
          to-do items associated with that critic will be removed from 
          the to-do pane.</para>

          <para>The V0.26 version of ArgoUML has a total of 90 critics, 
          a few of which are incompletely implemented. They are 
          described in detail by design issue category in the chapter 
          on critics (see <xref linkend="ch.ref.critics"/>).</para>

          <para>To the right of the list are a series of fields, titled 
          <literal>Critic Details</literal>, giving detailed control 
          over individual critics. Selecting a critic in the list on 
          the left will populate the fields for that critic.</para>

          <para>The first field on the right is titled <literal>Critic 
          Class:</literal> and then the full name of the class in 
          ArgoUML that implements the critic. This name can be used as 
          unique identifier of the critique, e.g. in conversations 
          about the critic.</para>

          <para>The first field below this title is a text box labeled 
          <literal>Headline:</literal> giving the complete headline of 
          the critic (which may be truncated in the list on the 
          left).</para>

          <note>

            <para>In the headline you may see the text <literal>
            &lt;ocl&gt;self&lt;/ocl&gt;</literal>, which will be 
            replaced by the name of the model element in question when the 
            critic is triggered.</para>

          </note>

          <para>The next field is a drop-down selector, labeled 
          <literal>Priority:</literal>. The three options available are 
          <literal>High</literal>, <literal>Medium</literal> and 
          <literal>Low</literal> and specify the priority category of 
          any to-do item generated by this critic. This does not alter 
          the priority of the already existing todo items, only the 
          newly generated ones. Changing the priority of a critic is 
          not saved persistently.</para>

          <para>The next field is labeled <literal>MoreInfo:</literal> 
          and contains a URL pointing to further information with a 
          button to the right labeled <literal>Go</literal> to navigate 
          to that URL.</para>

          <warning>

            <para>In the V0.26 release of ArgoUML there is no further 
            information available, and the <literal>Go</literal> button 
            is always grayed out and disabled.</para>

          </warning>

          <para>The next field is labeled <literal>
          Description:</literal> and is a text area with a detailed 
          explanation of what this critic means. If the text is too 
          large for the area a scroll bar is provided to the 
          right.</para>

          <note>

            <para>In this text area you may see the text <literal>
            &lt;ocl&gt;self&lt;/ocl&gt;</literal>, which will be 
            replaced by the name of the model element in question when the 
            critic is triggered.</para>

          </note>

          <para>The last field is a drop-down selector labeled <literal>
          Use Clarifier</literal>, with three options, <literal>
          Always</literal>, <literal>If Only One</literal> and <literal>
          Never</literal>.</para>

          <para>Clarifiers are the icons and wavy red underlines drawn 
          on the actual diagrams to indicate the artefact to which the 
          critic refers. The original intention was to make the mapping 
          from critics to clarifiers somewhat customizable.</para>

          <para>For example one user might make a <literal>Missing 
          Name</literal> critic show a red underline, another user 
          might turn off the clarifier, or have it draw a wavy green 
          underline or a blue questionmark. Critics with their 
          clarifier&apos;s disabled would still produce feedback that 
          is listed in the to-do pane.</para>

          <caution>

            <para>In the V0.26 release of ArgoUML this selector has no 
            function whatsoever. It is for future development.</para>

          </caution>

          <para>Underneath the fields are two buttons in a horizontal 
          row.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Wake</literal>. It is possible to snooze a 
              critic from the to-do pane (see 
              <xref linkend="ch.ref.todopane"/>), which makes the 
              critic inactive for a period. If the critic has been 
              snoozed, this button is enabled and will wake the critic 
              back up again. Otherwise it is grayed out.</para>

              <tip>

                <para>You can tell a snoozed critic, because in the 
                list on the left it will be indicated in the third 
                column.</para>

              </tip>

            </listitem>

            <listitem>

              <para><literal>Advanced</literal>. This button 
              causes ArgoUML to show a few columns extra
              in the table of critics. 
              It allows more detailed inspection 
              of critic properties.</para>

            </listitem>

          </itemizedlist>

          <para>Finally the bottom right of the dialog contains a 
          button labeled <literal>OK</literal>. Button&nbsp;1 click here 
          dismisses the dialog.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>The Tools Menu</title>

        <para>This menu provides a generic menu attachment point for 
        any plug-ins provided with ArgoUML. The standard system has no 
        plug-in, and this menu entry 
        is empty by 
        default.</para>

      </sect1>

      <sect1>

        <title>The Help Menu</title>

        <para>This menu provides help on the use of ArgoUML. It has two 
        entries.</para>

        <sect2>

          <title>System Information</title>

          <para>This menu entry brings up the system information 
          dialog, see <xref linkend="fig.ref.menu_help_system_info"/>
          </para>

          <figure float="1" id="fig.ref.menu_help_system_info">

            <title>The dialog for <literal>
            System Information</literal>.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_help_system_info.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>Use this menu to describe the system that runs ArgoUML 
          to the system manager or developer. Pressing the button 
          <literal>Run Garbage Collector</literal> not only runs the 
          Java gargage collector, but also refreshes the information 
          shown. To facilitate copy and paste into (e.g.) an email, the 
          button <literal>Copy Information to System 
          Clipboard</literal> is foreseen. The <literal>
          Cancel</literal> button dismisses the dialog box.</para>

        </sect2>

        <sect2 id="s2.ref.menu_help_about">

          <title>About ArgoUML</title>

          <para>This menu entry brings up the help window for ArgoUML 
          (see <xref linkend="fig.ref.menu_help"/>).</para>

          <figure float="1" id="fig.ref.menu_help">

            <title>The help window for ArgoUML</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/menu_help.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The window has six tabs, which are selected by button&nbsp;1 
          click. By default the first tab (<literal>Splash</literal>) 
          is shown.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Splash</literal>. This displays the 
              picture shown when ArgoUML starts up, and the current 
              version number.</para>

            </listitem>

            <listitem>

              <para><literal>Version</literal>. This provides version 
              information on the various packages that make up ArgoUML, 
              and some operating system and environment 
              information.</para>

            </listitem>

            <listitem>

              <para><literal>Credits</literal>. This details all those 
              who have created ArgoUML, including contact details for 
              the various module owners.</para>

            </listitem>

            <listitem>

              <para><literal>Contact Info</literal>. This gives the 
              major contact points for the ArgoUML project&mdash;the web 
              site, and the developers mailing list.</para>

            </listitem>

            <listitem>

              <para><literal>Report bugs</literal>. This gives 
              information about how to deal with bugs in ArgoUML. It is 
              important that all bugs are reported, and all cooperation 
              is appreciated.</para>

            </listitem>

            <listitem>

              <para><literal>Legal</literal>. A statement of the 
              FreeBSD license which covers all the ArgoUML 
              software.</para>

              <caution>

                <para>The various documentation of the project are not 
                all covered by FreeBSD (which is really meant for 
                software). In particular this manual is covered by the 
                OpenPub license (see <xref linkend="app.legal"/>
                ).</para>

              </caution>

            </listitem>

          </itemizedlist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.navpane">

      <title>The Explorer</title>

      <indexterm><primary>Explorer</primary></indexterm>
      <indexterm>
      <primary>Navigation</primary><secondary>Tree</secondary></indexterm>
      <indexterm>
      <primary>Navigation</primary><secondary>Pane</secondary></indexterm>
      <indexterm>
      <primary>Navigator</primary><secondary>Tree</secondary></indexterm>
      <indexterm>
      <primary>Navigator</primary><secondary>Pane</secondary></indexterm>
      <para>The Explorer was previously called Navigation Pane/Tree or 
      sometimes Navigator Pane/Tree.</para>

      <sect1>

        <title>Introduction</title>

        <para><xref linkend="fig.ref.navigation_pane"/> shows the 
        ArgoUML window, with the explorer highlighted.</para>

        <figure float="1" id="fig.ref.navigation_pane">
          <!-- This diagram shows the navigation overview. 
          It is a complete ArgoUML
          window, but with all except the explorer grayed out. This was
          done using GIMP with selected areas using Filters->Color->Map->
          Color Range Mapping from black to black & white to HSV 0,0,75.-->
          <title>Overview of the explorer</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/navigator_pane.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>The explorer allows the user to view the structure of the 
        model from a number of predefined perspectives. It also allows 
        the user to define their own perspetives for custom exploring 
        of the model.</para>

        <para>An important feature, related to the cognitive psychology 
        ideas behind ArgoUML is that not all model elements are necessarily 
        shown in all perspectives. Rather, the perspectives are used to 
        implement hiding of uninteresting parts of the model.</para>

      </sect1>

      <sect1 id="s1.ref.nav_mouse">

        <title>Mouse Behavior in the Explorer</title>

        <indexterm><primary>Explorer</primary><secondary>Mouse 
        Behavior</secondary></indexterm>
        <indexterm><primary>Mouse Behavior</primary><secondary>in the 
        Explorer</secondary></indexterm>
        <para>Behavior of the mouse in general, and the naming of the 
        buttons is covered in the chapter on the overall user interface 
        (see <xref linkend="ch.ref.ui"/>).</para>

        <sect2>

          <title>Button&nbsp;1 Click</title>

          <para>Within the hierarchical display, elements which have 
          sub-hierarchies are indicated by <guiicon>
          <inlinemediaobject><imageobject><imagedata align="center"
           fileref="images/icons/hierarchy_closed.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          when the hierarchy is hidden and <guiicon>
          <inlinemediaobject><imageobject><imagedata align="center"
           fileref="images/icons/hierarchy_open.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          when the hierarchy is open.</para>

          <para>Button&nbsp;1 click over the name of any diagram model element 
          will cause the diagram to be selected and displayed in the 
          editing pane. Its details will also be displayed in the 
          details pane.</para>

          <para>Button&nbsp;1 click over the name of any model element other than 
          a diagram in the main area of the explorer will cause it to 
          be selected, and its details shown in the details pane. If 
          the model element is part of a diagram currently displayed in the 
          editing pane, it will be highlighted there.</para>

          <note>

            <para>If the model element is part of a diagram other than that 
            currently displayed in the Editing Pane, there will be 
            <emphasis>no</emphasis> change of diagram in the Editing 
            Pane.</para>

          </note>

          <para>Where button&nbsp;2 click has been used to bring up a 
          context sensitive pop-up menu (see below), button&nbsp;1 click is 
          used to select the menu entry required. button&nbsp;1 click 
          outside the menu area will remove it.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Double Click</title>

          <para>This has the effect of a button&nbsp;1 single click, and if 
          the tree item was not a leaf, it will toggle the hierarchy 
          open or close.</para>

        </sect2>
        
        <sect2>

          <title>Button&nbsp;1 Motion</title>
          
          <para>Button&nbsp;1 motion means that you pick up one or more 
          modelelements, and drag them to a new location. 
          Dropping the modelelement somewhere 
          causes ArgoUML to execute some function 
          that depends on where you drop the modelelements. 
          </para>

          <sect3>
          <title>From Explorer to Explorer</title>
          <para>
          Releasing the mouse button above a namespace, 
          makes the modelelement owned by the namespace.
          In the Package-centric explorer perspective, this
          means a straigh-forward drag-and-drop function.
		  </para>
		  
		  <para>Use this drap and drop feature to easily move 
		  e.g. classes from one package into another.
		  </para>
		  </sect3>

          <sect3>
          <title>From Explorer to Diagram</title>
          <para>Dropping a modelelement on the diagram 
          is the equivalent of the "Add to Diagram" function.
          Hence, if the diagram did not yet show this modelelement, 
          it is added.
		  </para>
		  
		  <para>Use this drap and drop feature e.g. to easily create 
		  a diagram from imported XMI files. 
		  This because XMI files contain all the modelelements, 
		  but not any diagram information.
		  </para>
		  </sect3>

        </sect2>
        
        <sect2>

          <title>Button&nbsp;2 Actions</title>

          <para>When used in the the explorer, this will display a 
          selection dependent pop-up menu. Menu entries are highlighted 
          (but not selected) and sub-menus exposed by subsequent mouse 
          motion (without any buttons). Menu entry selection is with 
          button&nbsp;1 or button&nbsp;2.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Double Click</title>

          <para>This has no effect other than that of button&nbsp;2 single 
          click.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.explorer_keyboard">

        <title>Keyboard Behavior in the Explorer</title>

        <para>All keys active in a tree widget have their normal 
        behaviour.</para>

        <para>When a diagram is selected, pressing Ctrl-C will copy the 
        diagram in GIF format to the system clipboard.</para>

      </sect1>

      <sect1>

        <title>Perspective Selection</title>

        <para>The model elements in the ArgoUML model may be configured for 
        displaying in the tree by a number of perspectives. To this 
        end, a drop-down at the top allows selection of the explorer 
        perspective.</para>

        <para>Below that, there is a drop-down to select the ordering 
        of the atifacts within the hierarchy. The two possibilities are 
        &quot;Order by Type, Name&quot; and &quot;Order by Name&quot;. 
        The former groups all items per type, and sorts them per group 
        alphabetically on the name. The lattter simply sorts on name 
        only.</para>

        <para>The following explorer perspectives may be selected in 
        the drop-down at the top:</para>

        <itemizedlist>

          <listitem>

            <para><literal>Package-centric</literal> (the default). The 
            exploring hierarchy is organized by package hierarchy. The 
            top level shows the model. Under this are all the top level 
            packages in the model and all the model elements that are 
            directly in the namespace of the model.</para>

            <para>Beneath each package are all the model elements that sit 
            within the namespace of that package, including any further 
            sub-packages (which in turn have their own 
            sub-hierarchies).</para>

          </listitem>

          <listitem>

            <para><literal>Class-centric</literal>. 
            Shows classes in their package hierarchy as well as  
            datatypes and use case diagram elements. Similar to the  
            Package-centric view but it doesn't show connecting or  
            associating elements.  
            <!-- Got this from 
            http://www.devshed.com/c/a/Practices/Design-with-ArgoUML/3/ -->
            </para>

          </listitem>

          <listitem>

            <para><literal>Diagram-centric</literal>. In this view the 
            top level comprises all the diagrams in the model. Beneath 
            each diagram is a flat listing of all the model elements on the 
            diagram. Model elements that have sub-model elements that do not 
            appear on the diagram have their own hierarchy (for example 
            attributes and operations of classes).</para>

          </listitem>

          <listitem>

            <para><literal>Inheritance-centric</literal>. In this view 
            the top level shows the model. Beneath this are all 
            model elements that have no generalization in the model. Those 
            model elements that have specializations have a sub-hierarchy 
            showing the specializations.</para>

          </listitem>

          <listitem>

            <para><literal>Class Associations</literal>. In this view 
            the top level shows the model. Beneath this are all 
            diagrams and all classes. All classes that have 
            associations have a hierarchy tracking through the 
            associated classes.</para>

          </listitem>

          <listitem>

            <para><literal>Residence-centric</literal>. In this view 
            the model is shown at the top-level, with below it only 
            Nodes, and below these only components that reside on the 
            nodes, and below these components all elements that reside 
            on the components.</para>

          </listitem>

          <listitem>

            <para><literal>State-centric</literal>. In this view the 
            top level shows all the state machines and all activity 
            graphics associated with classes.</para>

            <para>Beneath each state machine is a hierarchy showing the 
            statechart diagram and all of the states. Beneath each state is 
            a list of the transitions in and out of the state.</para>

            <para>Beneath each activity graph is a hierarchy showing 
            the activity diagram and all of the action states. Beneath 
            each action state is a list of the transitions in and out 
            of the action state.</para>

          </listitem>

          <listitem>

            <para><literal>Transitions-centric</literal>. This is very 
            similar to <literal>State-centric</literal> view, but under 
            each state machine is listed the diagrams and all 
            transitions on the diagram, with states being shown as 
            sub-hierarchies under their connected transitions.</para>

            <para>Similarly under each activity graph is listed the 
            diagrams and all transitions on the diagram, with action 
            states being shown as sub-hierarchies under their connected 
            transitions.</para>

          </listitem>
          
          <listitem>

            <para><literal>Composite-centric</literal>. In this 
            view, all modelelements are shown
            according their composition in the UML metamodel.</para>

            <para>This perspective shows far more modelelements 
            then all others - it does not hide anything. 
            Hence, this view is not so user-friendly, but very suited
            for the UML specialist.</para>

          </listitem>

        </itemizedlist>

      </sect1>

      <sect1 id="s1.ref.configure_perspectives">

        <title>Configuring Perspectives</title>

        <para>The explorer is designed to be user configurable, to 
        allow the designer to view in his or her preferred way.</para>

        <sect2>

          <title>The Configure Perspectives dialog</title>

          <para>button&nbsp;1 click on the &quot;Configure 
          Perspectives&quot; icon (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/nav_config.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          at the top left of the explorer brings up the explorer 
          perspectives dialog (see 
          <xref linkend="fig.ref.navigator_pane_perspectives"/>).</para>

          <figure float="1" id="fig.ref.navigator_pane_perspectives">

            <title>The Configure Perspectives dialog box</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/navigator_pane_perspectives.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The top half of the dialog contains a list of all the 
          currently defined perspectives and to the right a series of 
          buttons stacked vertically. Button&nbsp;1 click can be used to 
          select a perspective. You can select only one perspective at 
          a time.</para>

          <para>Selecting a perspective reveals a text field above the 
          list, where the name of the perspective can be edited.</para>

          <para>The lower half of the dialog contains two list areas. 
          The one on the left, labeled <literal>
          Rules Library</literal>, contains the list of available rules 
          that may be used to create the perspective. The one on the 
          right, labeled <literal>Selected Rules</literal> contains the 
          actual rules chosen for the perspective that has been 
          selected in the list of perspectives at the top. In both 
          lists, you can select only one rule at a time.</para>

          <para>Separating the two areas in the lower half of the 
          dialog are buttons labeled <literal>&gt;&gt;</literal> and 
          <literal>&lt;&lt;</literal>. The first of these transfers the 
          rule selected in the library on the left to the list of rules 
          on the right&mdash;i.e. it adds a rule to the perspective. The 
          second one transfers the rule selected on the right to the 
          library list on the left&mdash;i.e. it removes a rule from the 
          perspective.</para>

          <para>If you hover the mouse over the horizontal line that 
          separates the two halves of the dialog, then you see it 
          change shape, to indicate that you can grab this line and 
          drag it up or down.</para>

          <para>All three titles of the lists show the number of 
          items in the list. ArgoUML V0.26 has 9 default perspectives, 
          and 72 rules in the library to build perspectives from.</para>

          <para>The buttons at the top right are explained as 
          follows:</para>

          <itemizedlist>

            <listitem>

              <para><literal>New</literal>. This creates a new 
              perspective from scratch with no rules selected, with an 
              automatically generated name.</para>

            </listitem>

            <listitem>

              <para><literal>Remove</literal>. This removes the 
              selected perspective.</para>

            </listitem>

            <listitem>

              <para><literal>Duplicate</literal>. This creates a copy 
              the selected perspective so it can be used as the basis 
              of a new perspective. The new one is named &quot;Copy 
              of&quot; followed by the original name.</para>

            </listitem>

            <listitem>

              <para><literal>Move Up</literal>. This moves the selected 
              perspective one place up in the list. This button is 
              downlighted for the topmost perspective.</para>

            </listitem>

            <listitem>

              <para><literal>Move Down</literal>. This moves the 
              selected perspective one place down in the list. This 
              button is downlighted for the last perspective.</para>

            </listitem>

            <listitem>

              <para><literal>Restore Defaults</literal>. This restores 
              all perspectives and their selected rules to the build-in 
              defaults of ArgoUML.</para>

            </listitem>

          </itemizedlist>

          <para>At the very bottom right is a button labeled <literal>
          OK</literal> to be used when all changes are complete. 
          button&nbsp;1 click on this button will close the dialog window. 
          The changes are saved when you exit ArgoUML in 
          the <literal>argo.user.properties</literal> file.</para>

          <para>Then there is the <literal>Cancel</literal> button, 
          which cancels all changes made in the dialog. Pressing the 
          dialog close icon (usually at the top right corner) has the 
          same effect as pressing the cancel button.</para>

        </sect2>

        <!--sect2>

          <title>The Explorer Panes</title>

          <para>The explorer was conceived as being able to offer 
          multiple views simultaneously, with up to three panels of 
          hierarchy. A dialog offers control of these panels, with an 
          option to show or not show each panel, and the option of the 
          second and third panels to be rooted at the selection on the 
          previous panel, or to show the previously used 
          hierarchy.</para>

          <caution>

            <para>This functionality is not yet implemented in ArgoUML. 
            The dialog is never shown.</para>

          </caution>

          <para>When using the explorer, it is worth bearing in mind 
          that this is a useful visualization of the model, it is not 
          <emphasis>solely</emphasis> for navigation and selection. It 
          is also useful for users to easily (meaning a few mouse 
          clicks without having to arrange a diagram) visualize the 
          model structured according to some perspective. For example, 
          show me the state nesting, or show me the class inheritance 
          tree, or show me the package nesting, or show me the list of 
          actors.</para>

          <para>The idea with the second and third explorer tree panes, 
          is that sometimes it is easier to explore the tree to a 
          certain level in one tree and then continue expanding in a 
          second tree. Since each tree will not be so deep, it will 
          look more like a list.</para>

          <para>For example, look at the way javadocs are viewed with 
          frames: the packages are selected from one list, and 
          interfaces, classes, and exceptions in that package are shown 
          in a second pane. In the case of javadocs, the second pane 
          has a tree with three roots that are always expanded, but it 
          is visually presented as three lists with three 
          headers.</para>

          <para>The other suggested use of a second or third nav panel 
          is to list recently visited model elements. This is simliar 
          to the recently visited files listed on the <literal>
          File</literal> menu of most applications, but for model 
          elements rather than files.</para>

          <para>The motivtion is the fact that designers frequently 
          <quote>interrupt</quote> themselves: they are thinking of 
          working on one part of the design, and then they make a 
          decision that needs a change in some other part, and then 
          that has an implication on some other part, and... and... and... 
          the designer forgets what it was they were originally trying 
          to accomplish. They need to <quote>pop their mental 
          stack</quote> to come back to finish what the started. If 
          they fail to do that, they leave half-finished fragments all 
          over the design which always seem to come out as soon as it 
          is presented to someone else.</para>

          <para>A recently visited list should be LIFO (stack) ordered, 
          or FIFO (queue) ordered. The goal would be to help designers 
          come back to finish what they were doing, or simply to help 
          them switch between two or three related parts of the design. 
          The <literal>Navigate Back</literal> and <literal>Navigate 
          Forward</literal> buttons in the toolbar serve the same basic 
          purpose and use a lot less screen space.</para>

          <para>Tear-off tabs would also help with alternating between 
          views, but sometimes users don&apos;t want to work with so 
          many separate windows.</para>

          <para>This is the theory that motivates the idea of multiple 
          nav panes. For more information see Jason Robbins&apos; PhD 
          dissertation 
          <ulink url="http://argouml.tigris.org/docs/robbins_dissertation/">
          http://argouml.tigris.org/docs/robbins_dissertation/</ulink>. 
          One practical usability concern is available screen space and 
          another is visual complexity. For this reason the multiple 
          panes have yet to be implemented in ArgoUML while more 
          pressing issues are addressed.</para>

        </sect2-->

      </sect1>

      <sect1>

        <title>Context Sensitive Menu</title>

        <para>Button&nbsp;2 Click over any selected model element in the main 
        area of the explorer will cause a pop-up menu to appear.</para>
        
        <para>The presence of all these menu entries depends on the 
          selected element(s), 
          and other circumstances. 
          E.g. the "Create ModelElement" submenu is not present 
          on modelelements that are 
          part of a non-editable profile element.</para>

        <sect2>
          <title>Create Diagram</title>
          
          <para>This entry on the pop-up menu opens a choice
            of submenus, one for each diagram type. </para>
          <para>The namespace of the new diagram 
            will be based on the selected modelelement.</para>
        </sect2>

        <sect2>
          <title>Create ModelElement</title>
          
          <!-- Added thanks to issue 1009. -->
          <para>This entry on the pop-up menu opens a choice
            of submenus, one for each model element. </para>
          <para>The new model element 
            will be composed by the selected modelelement.</para>
          <para>Selecting multiple elements leads to different menu items, 
            e.g. selecting 2 classes 
            allows the creation of several kinds of relationships.</para>
        </sect2>

        <sect2>
          <title>Copy Diagram to Clipboard as Image</title>
          
          <para>This entry on the pop-up menu creates a graphical file,
          in the default graphical format, and puts it on the clipboard of your PC. 
          The graphics can inmediately be pasted into 
          e.g. a requirements document in OpenOffice.Org.</para>
          
          <para>The graphics format and its resolution are determined by 
          ArgoUML's default setting: Select in the menu 
          <literal>Edit</literal>, then <literal>Settings...</literal>,
          then the tab <literal>Environment</literal>.
          The PNG and GIF formats are advised, 
          and the resolution <literal>Standard</literal>.
          </para>
          
          <tip><para>Some applications (such as Doors from Telelogic) 
          require the background color 
          of the generated graphics to be adapted (else the image is empty). 
          This can be done with a tool like IrfanView; 
          it is as easy as clicking its paste button, 
          and then its copy button.
          </para></tip>
        </sect2>
         
        <sect2>

          <title>Add to Diagram</title>

          <para>This entry on the pop-up menu appears for any model element 
          that could be added to the diagram in the editing pane.</para>

          <para>The item can be placed in a diagram by moving the 
          cursor to the editing pane or a spawned editing pane window 
          (where it will appear as a cross) and clicking 
          button&nbsp;1.</para>

          <caution>

            <para>This menu entry only appears as not grayed out, if 
            the diagram in the editor pane allows to contain the 
            model element, and the model element is not present yet in the 
            diagram. ArgoUML will not let you place more than one copy 
            of any particular model element on a diagram.</para>

          </caution>

        </sect2>

        <sect2>

          <title><guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/delete_from_model.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          Delete From Model</title>

          <para>This entry on the pop-up menu appears for any model element 
          that could be deleted from the model.</para>

          <warning>

            <para>This deletes the model element from the model completely, 
            not just from the diagram. To remove the model element just from 
            the diagram, use the edit menu (see 
            <xref linkend="s2.menu_edit_remove_from_diagram"/>).</para>

          </warning>

          <caution>

            <para>You can delete a diagram from the model. Depending on 
            the type of diagram, that might delete all model elements shown 
            on the diagram. To illustrate the differences, consider the 
            following examples:</para>

            <itemizedlist>

              <listitem>

                <para>Deleting a class diagram does not delete any 
                model element drawn on it. All model elements that were shown on 
                the diagram remain present in the model. This because a 
                class diagram does not &quot;map&quot; on any model element 
                according the UML standard V1.4.</para>

              </listitem>

              <listitem>

                <para>Deleting a statechart diagram also deletes the 
                statemachine it represents, and hence also all the 
                model elements owned by the statemachine. This because a 
                statechart diagram does &quot;map&quot; into a 
                StateMachine according the UML standard V1.4.</para>

              </listitem>

            </itemizedlist>

          </caution>

        </sect2>

        <sect2>

          <title>Set Source Path... (To be written)</title>

          <para>This entry on the pop-up menu ...</para>

        </sect2>

        <sect2>

          <title>Add Package</title>

          <para>This entry on the pop-up menu is available whenever a 
          model element is selected that may contain a package, e.g. a 
          package. After activating this menu the model element will own a 
          new package.</para>

        </sect2>

        <sect2>

          <title>New Stereotype</title>

          <para>This entry on the pop-up menu is available ...
          (to be written)</para>

        </sect2>

        <sect2>

          <title>Add All Classes in Namespace</title>

          <para>This entry on the pop-up menu is available for Class 
          Diagrams only. Activating this menu-item will add all classes 
          in the current namespace to the diagram. They will be located 
          at the top left corner&mdash;obviously a perfect occasion to use 
          the <quote>Arrange-&gt;Layout</quote> function in the 
          menu.</para>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.editpane">

      <title>The Editing Pane</title>

      <sect1>

        <title>Introduction</title>

        <para><xref linkend="fig.ref.editing_pane"/> shows the ArgoUML 
        window with the editing pane highlighted.</para>

        <figure float="1" id="fig.ref.editing_pane">

          <title>Overview of the editing pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/editing_pane.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>This is where all the diagrams are drawn. In earlier 
        versions of ArgoUML this pane went under a variety of names. 
        You may encounter <quote>drawing pane</quote>, <quote>diagram 
        pane</quote> or <quote>multi-editor pane</quote> in other 
        documentation that is still being updated.</para>

        <para>The pane has a tool bar at the top, and a single tab 
        labeled <literal>As Diagram</literal> at the bottom, which has 
        no function in the 0.20 version of ArgoUML. The main area shows 
        the currently selected diagram, of which the name is shown in 
        the window title bar.</para>

      </sect1>

      <sect1 id="s1.ref.edit_mouse">

        <title>Mouse Behavior in the Editing Pane</title>

        <para>Behavior of the mouse in general, and the naming of the 
        buttons is covered in the chapter on the overall user interface 
        (see <xref linkend="ch.ref.ui"/>).</para>

        <sect2>

          <title>Button&nbsp;1 Click</title>

          <para>In the tool bar of the editing pane, button&nbsp;1 click is 
          used to select a tool for creating a new model element and adding 
          it to the diagram (see double clicking for creating multiple 
          model elements). For most tools, adding a new model element to the 
          diagram is achieved by moving the mouse into the editing area 
          and clicking again.</para>

          <para>In the main editing area button&nbsp;1 click is used to 
          select an individual model element.</para>

          <para>Many model elements (e.g. actor, class) show special handles 
          when selected and the mouse hovers over them. These are 
          called <quote>Selection Action Buttons</quote>, see 
          <xref linkend="s1.ref.edit_pane_selection_action_buttons"/>. 
          They appear at the sides, top and bottom, and indicate a 
          relationship type. Clicking on a Selection Action Button 
          creates a new related model element, with the relation of the type 
          that was indicated. If the shift key is pressed when hovering 
          the mouse over a selected model element, sometimes different 
          handles are shown, which stand for different relation 
          types.</para>

          <para>Where button&nbsp;2 click has been used to bring up a 
          context sensitive pop-up menu (see below), button&nbsp;1 click is 
          used to select the menu entry required. The pop-up menu will 
          be removed by any button&nbsp;1 click outside of the menu 
          area.</para>

          <para>There are various more detailed effects, which are 
          discussed under the descriptions of the various tools (see 
          <xref linkend="s1.ref.edit_pane_tool_bar"/>).</para>

        </sect2>

        <sect2 id="s2.ref.edit_button1_double_click">

          <title>Button&nbsp;1 Double Click</title>

          <para>When used on the tool bar with a tool to add a 
          model element, the selected model element will be added multiple times 
          to the drawing area, once for each further button click, 
          until the tool is again selected or another tool 
          chosen.</para>

          <para>When used within the drawing area on a model element that 
          has sub-components, double click will select the 
          sub-component for editing (creating it if necessary).</para>

          <para>For example double clicking over an operation 
          compartment of a class will select the operation. Or create 
          one if there is none yet.</para>

          <para>A special use is with package model elements on the class 
          diagram. A double click on a package will navigate to the 
          class diagram associated with a package (the first created if 
          there is more than one), or will offer to create one for you 
          if there is none. See 
          <xref linkend="fig.ref.edit_add_class_diagram"/></para>

          <figure float="1" id="fig.ref.edit_add_class_diagram">

            <title>The dialog for adding a new class diagram</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/edit_add_class_diagram.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Motion</title>

          <!-- This has never worked AFAIK!
          <para>When adding a model element using the toolbar, button&nbsp;1 
          motion can generally be used to define the size of the new 
          model element. Its dimensions (line ends, diagonal corners of a 
          rectangular model element etc) are defined by button&nbsp;1 down and 
          button&nbsp;1 up.</para>
          -->

          <para>Where the model element being added is some form of 
          connector its termination point is shown with button&nbsp;1 up 
          over the terminating model element. button&nbsp;1 click may be used in 
          the space between model elements to create articulation points in 
          the connector. This is particularly useful where connectors 
          must loopback on themselves.</para>

          <para>Over graphical model elements button&nbsp;1 motion will move the 
          model element to a new position.</para>

          <para>Graphical model elements that are selected show handles at 
          the corners or ends, and these can be used for 
          re-sizing.</para>

          <para>Some model elements (e.g. actor, class) show special handles 
          (called <quote>Selection Action Buttons</quote>, see 
          <xref linkend="s1.ref.edit_pane_selection_action_buttons"/>) 
          at the sides, top and bottom, which can be dragged to form 
          types of relationship with other model elements.</para>

          <para>Where the model element is some form of connector between 
          other items, button&nbsp;1 motion other than at a handle will 
          cause a new handle to be created, allowing the connector to 
          be articulated at that point. This only works when the 
          connecting line is not straight angled. Such new handles can 
          be removed by moving them to the end of the connector.</para>

          <para>There are various more detailed effects, which are 
          discussed under the descriptions of the various tools (see 
          <xref linkend="s1.ref.edit_pane_tool_bar"/>).</para>

        </sect2>

        <sect2>

          <title>Shift and Ctrl modifiers with Button&nbsp;1</title>

          <para>Where multiple selections are to be made, the CTRL key 
          is used with button&nbsp;1 to <emphasis>add</emphasis> unselected 
          model elements to the current selection. Where a model element is 
          already selected, it is removed from the current 
          selection.</para>

          <para>Clicking Button&nbsp;1 while the SHIFT key is pressed, 
          invokes the broom tool, which causes the selected model elements 
          (and any others swept up with them) to be moved with the 
          broom tool (see <xref linkend="s2.ref.edit_layout"/>).</para>

        </sect2>

        <sect2>

          <title>Alt with Button&nbsp;1 motion</title>

          <para>Button&nbsp;1 down anywhere in the diagram while the ALT key 
          is pressed, allows to scroll the canvas in all directions 
          with button&nbsp;1 motion.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Actions</title>

          <para>When used over model elements in the the editing pane, this 
          will display a context dependent pop-up menu. Menu entries 
          are highlighted (but not selected) and sub-menus exposed by 
          subsequent mouse motion (without any buttons). Menu entry 
          selection is with button&nbsp;1 or button&nbsp;2. See 
          <xref linkend="s1.ref.edit_pane_pop_up"/> for details of the 
          specific pop-up menus.</para>

          <para>In case multiple elements are selected, the pop-up menu 
          only appears if all the items are of the same kind. 
          In this case, the 
          functions apply to all selected elements.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Double Click</title>

          <para>This has no effect other than that of button&nbsp;2 single 
          click.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Motion</title>

          <para>This is used to select items in a context sensitive 
          menu popped up by use of button&nbsp;2 click.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.edit_pane_keyboard">

        <title>Keyboard Behavior in the Editing Pane</title>

        <para>Many keyboard shortcuts can be used when the editing pane
        is active, mainly to change the selection or to move across the
        model elements.</para>

        <sect2>

          <title>Nudging a model element</title>

          <para>You can nudge a fig by selecting an element and using
          arrow keys. Keeping the shift or the alt key pressed will produce
          a wider movement.</para>

        </sect2>

        <sect2>

          <title>Moving across the model elements</title>

          <para>You can select the model element nearer to the selected one by 
          using the arrow keys while clicking the right button of the mouse.
          You can also select the next model element using the tab key, or the
          previous using the ctrl+tab keys.</para>

        </sect2>

      </sect1>
      
      <sect1 id="s1.ref.edit_pane_tool_bar">

        <title>The tool bar</title>

        <para>The toolbar at the top of the editing pane provides the 
        main functions of the pane. The default tool is the <literal>
        Select</literal> tool (<guiicon><inlinemediaobject><imageobject>
        <imagedata align="center" fileref="images/icons/select.gif"
         format="GIF"/></imageobject></inlinemediaobject></guiicon>). 
        In general button&nbsp;1 click on any tool selects a tool for one 
        use, before reverting to the default tool, and button&nbsp;1 double 
        click selects a tool for repeated use.</para>

        <para>The tools fall into four categories.</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Layout tools.</emphasis> Provide assistance 
            in laying out model elements on the diagram.</para>

          </listitem>

          <listitem>

            <para><emphasis>Annotation tools.</emphasis> Used to 
            annotate model elements on the diagram.</para>

          </listitem>

          <listitem>

            <para><emphasis>Drawing tools.</emphasis> Used to add 
            general graphic objects to diagrams.</para>

          </listitem>

          <listitem>

            <para><emphasis>Diagram specific tools.</emphasis> Used to 
            add UML model elements specific to a particular diagram type to 
            the diagram.</para>

          </listitem>

        </itemizedlist>
        
        <para>Some of the tools that are generally not all used so often, 
        are combined in a dropdown, 
        to take less space on the toolbar. 
        See e.g. <xref linkend="fig.ref.edit_graphical_tools"/>.
        Press the symbol at the right of the tool to pop it open.
        These drop-down tools remember their last used tool persistently. 
        This means that when ArgoUML starts, 
        they show the last tool that was activated 
        the previous time ArgoUML was run.
        </para>

        <sect2 id="s2.ref.edit_layout">

          <title>Layout Tools</title>

          <para>The following two tools are provided in all diagrams in 
          this category.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/select.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Select</literal>. This tool provides for general 
              selection of model elements on the diagram. Button&nbsp;1 click 
              will select a model element. CTRL with button&nbsp;1 can be used 
              to select (or deselect) multiple model elements. Button&nbsp;1 
              motion will move selected 2D items or add and move a new 
              control point on a link. Button&nbsp;1 motion on a selected 
              component&apos;s control point will stretch that 
              component&apos;s shape.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/broom.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <emphasis>Broom</emphasis>. Button&nbsp;1 motion with this 
              tool provide a <quote>broom</quote> which will sweep all 
              model elements along. This is a very shortcut way of lining 
              things up.</para>

              <para>The Broom can also be invoked by using SHIFT with 
              button&nbsp;1 motion when the <literal>Select</literal> tool 
              is in use.</para>

              <para>The Broom is discussed at length in its own 
              chapter, see <xref linkend="s1.ref.edit_pane_broom"/>
              </para>

            </listitem>

          </itemizedlist>

          <tip>

            <para>Additional control of model element layout is provided 
            through the <literal>Arrange</literal> menu (see 
            <xref linkend="s1.ref.menu_arrange"/>).</para>

          </tip>

        </sect2>

        <sect2>

          <title>Annotation Tools</title>

          <para>The annotation tool <literal>Comment</literal> (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center" fileref="images/icons/note.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          is used to add a comment to a selected UML model element.</para>

          <caution>

            <para>Unlike most other tools you use the <literal>
            Select</literal> tool to select a model element, and then 
            button&nbsp;1 click on <literal>Comment</literal> to create the 
            comment. If no element is selected when the comment tool is 
            clicked, then the comment is created and put at the left 
            top corner.</para>

          </caution>

          <para>The comment is created alongside the selected model element, 
          empty by default. The text can be selected with button&nbsp;1 
          double-click and edited from the keyboard.</para>

          <para>The UML standard allows comments to be attached to any 
          model element.</para>

          <para>You can link any comment to aditional elements using 
          the <literal>CommentLink</literal> (
          <guiicon><inlinemediaobject><imageobject>
          <imagedata align="center"
           fileref="images/icons/commentlink.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
          tool.</para>

        </sect2>

        <sect2 id="s2.ref.edit_pane_drawing_tools">

          <title>Drawing Tools</title>

          <para>These are a series of tools for providing graphical 
          additions to diagrams. Although they are not UML model elements, 
          the UML standard provides for such decoration to improve the 
          readability of diagrams.</para>

          <tip>

            <para>These drawing tools provide a useful way to partially 
            support some of the UML features (such as general purpose 
            notes) that are missing from the current release of 
            ArgoUML.</para>

          </tip>

          <para>Eight tools are provided, all grouped into one 
          drop-down widget. See 
          <xref linkend="fig.ref.edit_graphical_tools"/>. Button&nbsp;1 
          click on the diagram will place an instance of the graphical 
          item of the same size as the last one placed. The size can be 
          controlled by button&nbsp;1 motion during placement. One side or 
          end of the element will be at button&nbsp;1 down, the other side 
          or end at button&nbsp;1 up. In general after they are placed on 
          the diagram, graphical elements can be dragged with the 
          <literal>Select</literal> tool and button&nbsp;1 and re-sized by 
          button&nbsp;1 motion on the handles after they have been 
          selected.</para>

          <figure float="1" id="fig.ref.edit_graphical_tools">

            <title>The drawing tools selector.</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/edit_graphical_tools.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/rectangle.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Rectangle</literal>. Provides a rectangle.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/rounded_rectangle.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Rounded Rectangle</literal>. Provides a 
              rectangle with rounded corners. There is no control over 
              the degree of rounding.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/circle.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Circle</literal>. Provides a circle.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/line.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Line</literal>. Provides a line.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/text.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Text</literal>. Provides a text box. The text is 
              entered by selecting the box and typing. Text is centered 
              horizontally and after typing, the box will shrink to the 
              size of the text. However it can be re-sized by dragging 
              on the corners.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/polygon.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Polygon</literal>. Provides a polygon. The 
              points of the polygon are selected by button&nbsp;1 click and 
              the polygon closed with button&nbsp;1 double click (which will 
              link the final point to the first point).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/spline.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Spline</literal>. Provide an open spline. The 
              control points of the spline are selected with button&nbsp;1 
              and the last point selected with button&nbsp;1 double 
              click.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/ink.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Ink</literal>. Provide a polyline. The points 
              are provided by button&nbsp;1 motion.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Use Case Diagram Specific Tools</title>

          <para>Several tools are provided specific to UML model elements on 
          use case diagrams. The detailed properties of these model elements 
          are described in the section on use case diagram model elements 
          (see <xref linkend="ch.ref.entusecase"/>).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/actor.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Actor</literal>. Add an actor to the diagram. 
              For convenience, when the mouse is over a selected actor 
              it displays two handles to left and right which may be 
              dragged to form association relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/use_case.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Use Case</literal>. Add a use case to the 
              diagram. For convenience, when the mouse is over a 
              selected use case it displays two handles to left and 
              right which may be dragged to form association 
              relationships and two handles top and bottom which may be 
              dragged to form generalization and specialization 
              relationships respectively.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association</literal>. Add an association 
              between two model elements selected using button&nbsp;1 motion 
              (from the first model element to the second). There are 6 
              types of association offered here, see 
              <xref linkend="fig.ref.edit_association_tools"/>: 
              <literal>association</literal>, <literal>
              aggregation</literal> and <literal>composition</literal>, 
              and all these three can be <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

              <figure float="1" id="fig.ref.edit_association_tools">

                <title>The association tool selector.</title>

                <screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_association_tools.png"
                 format="PNG"/></imageobject></mediaobject></screenshot>
              </figure>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/dependency.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Dependency</literal>. Add a dependency between 
              two model elements selected using button&nbsp;1 motion (from the 
              dependent model element).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/generalization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Generalization</literal>. Add a generalization 
              between two model elements selected using button&nbsp;1 motion 
              (from the child to the parent).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/extend.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Extend</literal>. Add an extend relationship 
              between two model elements selected using button&nbsp;1 motion 
              (from the extended to the extending use case).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/include.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Include</literal>. Add an include relationship 
              between two model elements selected using button&nbsp;1 motion 
              (from the including to the included use case).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/extension_point.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Add Extension Point</literal>. Add an extension 
              point to a selected use case. The extension point is 
              given the default name <literal>newEP</literal> and 
              location <literal>loc</literal>. Where the extension 
              point compartment is displayed, the extension point may 
              be edited by button&nbsp;1 double click and using the 
              keyboard, or by selecting with button&nbsp;1 click (after the 
              use case has been selected) and using the property tab. 
              Otherwise it may be edited through its property tab, 
              selected through the property tab of the owning use 
              case.</para>

              <note>

                <para>This tool is grayed out except when a use case is 
                selected.</para>

              </note>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Class Diagram Specific Tools</title>

          <para>Several tools are provided specific to UML model elements on 
          class diagrams. The detailed properties of these model elements 
          are described in the section on class diagram model elements (see 
          <xref linkend="ch.ref.entclass"/>).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/package.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Package</literal>. Add a package to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/class.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Class</literal>. Add a class to the diagram. For 
              convenience, when the mouse is over a selected class it 
              displays two handles to left and right which may be 
              clicked or
              dragged to form association relationships (or composition 
              in case SHIFT has been pressed) and two handles top and 
              bottom which may be dragged or clicked
              to form generalization and 
              specialization relationships respectively.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association</literal>. Add an association 
              between two model elements selected using button&nbsp;1 motion 
              (from the first model element to the second). There are 2 
              types of association offered here, <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/aggregation_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Aggregation</literal>. Add an aggregation
              between two model elements selected using button&nbsp;1 motion 
              (from the first model element to the second). There are 2
              types of aggregation offered here, <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/composition_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Composition</literal>. Add an composition 
              between two model elements selected using button&nbsp;1 motion 
              (from the first model element to the second). There are 2 
              types of composition offered here, <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_end.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association-end</literal>. Add 
              another end to an already existing association 
              using button&nbsp;1 (from the 
              association middle to a class, or vice versa).
              This is the way to create so-calld N-ary associations.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/generalization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Generalization</literal>. Add a generalization 
              between two model elements selected using button&nbsp;1 (from the 
              child to the parent).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/interface.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Interface</literal>. Add an interface to the 
              diagram. For convenience, when the mouse is over a 
              selected interface it displays a handle at the bottom 
              which may be dragged to form a realization relationship 
              (the target being the realizing class).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/realization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Realization</literal>. Add a realization between 
              a class and an interface selected using button&nbsp;1 motion 
              (from the realizing class to the realized 
              interface).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/dependency.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Dependency</literal>. Add a dependency between 
              two model elements selected using button&nbsp;1 motion (from the 
              dependent model element). There are also 2 special types of 
              dependency offered here, <literal>Permission</literal> (
              <guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/permission.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
              and <literal>Usage</literal> (
              <guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/usage.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon>).
               A <literal>Permission</literal> is created by default 
               with stereotype <literal>Import</literal>, and is used to import
               elements from one package into another.
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Attribute</literal>. Add a new attribute to the 
              currently selected class. The attribute is given the 
              default name <literal>newAttr</literal> of type <literal>
              int</literal> and may be edited by button&nbsp;1 double click 
              and using the keyboard, or by selecting with button&nbsp;1 
              click (after the class has been selected) and using the 
              property tab.</para>

              <note>

                <para>This tool is grayed out except when a class is 
                selected.</para>

              </note>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Operation</literal>. Add a new operation to the 
              currently selected class or interface. The operation is 
              given the default name <literal>newOperation</literal> 
              with no arguments and return type <literal>void</literal> 
              and may be edited by button&nbsp;1 double click and using the 
              keyboard, or by selecting with button&nbsp;1 click (after the 
              class has been selected) and using the property 
              tab.</para>

              <note>

                <para>This tool is grayed out except when a class or 
                interface is selected.</para>

              </note>

            </listitem>
            
            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/associationclass.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association Class</literal>. 
              Add a new association class 
              between two model elements selected using button&nbsp;1 motion 
              (from the first model element to the second).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Datatype</literal>. 
              Add a datatype to the 
              diagram. For convenience, when the mouse is over a 
              selected datatype it displays handles 
              at the top and at the bottom 
              which may be clicked or dragged 
              to form a generalization relationship 
              (the target being another datatype).
              There are 2 other elements available here, 
              <guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Enumeration</literal>
              and
              <guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Stereotype</literal>.
              These two have similar handles, 
              except the one at the top of a stereotype: 
              when clicked, it creates a metaclass, 
              connected by a dependency marked with &laquo;stereotype&raquo;.
              This eases the creation of "stereotype declaration" diagrams - 
              see the literature on the subject.
              </para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Sequence Diagram Specific Tools</title>

          <para>Seven tools are provided specific to UML model elements on 
          sequence diagrams. The detailed properties of these model elements 
          are described in the section on sequence diagram model elements 
          (see <xref linkend="ch.ref.entseq"/>).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/classifierrole_sd.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>ClassifierRole</literal>. Add a classifierrole to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/call_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Message with Call Action</literal>. 
              Add a call message 
              between two classifierroles selected using button&nbsp;1 motion (from 
              the originating classifierrole to the receiving classifierrole).
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/return_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Message with Return Action</literal>. 
              Add a return message 
              between two classifierroles selected using button&nbsp;1 motion (from 
              the originating classifierrole to the receiving classifierrole).
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/create_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Message with Create Action</literal>. 
              Add a create message 
              between two classifierroles selected using button&nbsp;1 motion (from 
              the originating classifierrole to the receiving classifierrole).
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/destroy_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Message with Destroy Action</literal>. 
              Add a destroy message 
              between two classifierroles selected using button&nbsp;1 motion (from 
              the originating classifierrole to the receiving classifierrole).
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/sequence_expand.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Add Vertical Space to Diagram</literal>.  
              Add vertical space to a diagram by moving all messages
              below this down.  Click the mouse at the point where you 
              want the space to be added and drag down the screen vertically
              the distance which matches the height of the space you'd 
              like to have added.
              </para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/sequence_contract.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Remove Vertical Space in Diagram</literal>. 
              Remove vertical space from diagram and move all elements
              below up vertically.  Click and drag the mouse vertically
              over the space that you want deleted.
              </para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Collaboration Diagram Specific Tools</title>

          <para>Three tools are provided specific to UML model elements on 
          collaboration diagrams. The detailed properties of these 
          model elements are described in the section on collaboration 
          diagram model elements (see <xref linkend="ch.ref.entcollab"/>
          ).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/classifier_role.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Classifier Role</literal>. Add a classifier role 
              to the diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association Role</literal>. Add an association 
              role between two classifier roles selected using button&nbsp;1 
              motion (from the originating classifier role to the 
              receiving classifier role). There are 6 types of 
              association roles offered here, see 
              <xref linkend="fig.ref.edit_association_tools"/>: 
              <literal>association</literal>, <literal>
              aggregation</literal> and <literal>composition</literal>, 
              and all these three can be <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/generalization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Generalization</literal>. Add a generalization 
              between two model elements selected using button&nbsp;1 (from the 
              child to the parent).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/dependency.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Dependency</literal>. Add a dependency between 
              two model elements selected using button&nbsp;1 motion (from the 
              dependent model element).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/message.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Add Message</literal>. Add a message to the 
              selected association role.</para>

              <note>

                <para>This tool is grayed out except when an 
                association role is selected.</para>

              </note>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Statechart Diagram Specific Tools</title>

          <para>Eleven tools are provided specific to UML model elements on 
          statechart diagrams. The detailed properties of these model elements 
          are described in the section on statechart diagram model elements 
          (see <xref linkend="ch.ref.entstate"/>).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Simple State</literal>. Add a simple state to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/composite_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Composite State</literal>. Add a composite state 
              to the diagram. All model elements that are subsequently 
              placed on the diagram on top of the composite state will 
              form part of that composite state.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/transition.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Transition</literal>. Add a transition between 
              two states selected using button&nbsp;1 motion (from the 
              originating state to the receiving state).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/synchstate.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Synch State</literal>. Add a synchstate to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/submachinestate.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Submachine State</literal>. Add a submachinestate to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stubstate.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Stub State</literal>. Add a stubstate to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/initial_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Initial</literal>. Add an initial pseudostate to 
              the diagram.</para>

              <caution>

                <para>There is nothing to stop you adding more than one 
                initial state to a diagram or composite state. However 
                to do so is meaningless, and one of the critics will 
                complain.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/final_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Final State</literal>. Add a final state to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/junction.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Junction</literal>. Add a junction pseudostate 
              to the diagram.</para>

              <caution>

                <para>A well formed junction should have at least one incoming 
                transition and at least one outgoing. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any junction that does not follow this rule.</para>

              </caution>
            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/branch.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Choice</literal>. Add a choice pseudostate to 
              the diagram.</para>

              <caution>

                <para>A well formed choice should have at least one incoming 
                transition and at least one outgoing. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any choice that does not follow this rule.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/fork.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Fork</literal>. Add a fork pseudostate to the 
              diagram.</para>

              <caution>

                <para>A well formed fork should have exactly one incoming 
                transition and two or more outgoing. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any fork that does not follow this rule.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/join.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Join</literal>. Add a join pseudostate to the 
              diagram.</para>

              <caution>

                <para>A well formed join should have exactly one outgoing 
                transition and two or more incoming. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any join that does not follow this rule.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/shallow_history.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Shallow History</literal>. Add a shallow history 
              pseudostate to the diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/deep_history.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Deep History</literal>. Add a deep history 
              pseudostate to the diagram.</para>

            </listitem>
            
            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/call_event.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Call Event</literal>. Add a Call Event as trigger
              to a transition.
              There are 4 types of 
              events offered here: 
              <literal>Call Event</literal>, <literal>
              Change Event</literal>, 
              <literal>Signal Event</literal> and <literal>
              Time Event</literal>.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/guard.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Guard</literal>. Add a guard 
              to a transition.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/call_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Call Action</literal>. Add a call action 
              (i.e. the effect)
              to a transition.
              There are 7 types of 
              actions offered here: 
              <literal>Call Action</literal>, 
              <literal>Create Action</literal>, 
              <literal>Destroy Action</literal>, 
              <literal>Return Action</literal>, 
              <literal>Send Action</literal>, 
              <literal>Terminate Action</literal>, 
              <literal>Uninterpreted Action</literal> and 
              <literal>Action Sequence</literal>.
              </para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Activity Diagram Specific Tools</title>

          <para>Seven tools are provided specific to UML model elements on 
          activity diagrams. The detailed properties of these model elements 
          are described in the section on activity diagram model elements 
          (see <xref linkend="ch.ref.entactiv"/>).</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/action_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Action State</literal>. Add an action state to 
              the diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/transition.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Transition</literal>. Add a transition between 
              two action states selected using button&nbsp;1 motion (from 
              the originating action state to the receiving action 
              state).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/initial_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Initial</literal>. Add an initial pseudostate to 
              the diagram.</para>

              <caution>

                <para>There is nothing to stop you adding more than one 
                initial state to a diagram. However to do so is 
                meaningless, and one of the critics will 
                complain.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/final_state.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Final State</literal>. Add a final state to the 
              diagram.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/junction.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Junction</literal>. Add a junction (decision) 
              pseudostate to the diagram.</para>

              <caution>

                <para>A well formed junction should have one incoming 
                transition and two or more outgoing. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any junction that does not follow this rule.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/fork.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Fork</literal>. Add a fork pseudostate to the 
              diagram.</para>

              <caution>

                <para>A well formed fork should have one incoming 
                transition and two or more outgoing. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any fork that does not follow this rule.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/join.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Join</literal>. Add a join pseudostate to the 
              diagram.</para>

              <caution>

                <para>A well formed join should have one outgoing 
                transition and two or more incoming. ArgoUML does not 
                enforce this, but an ArgoUML critic will complain about 
                any join that does not follow this rule.</para>

              </caution>

            </listitem>
            
            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/callstate.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>CallState</literal>. Add a callstate to the 
              diagram. 
              A call state is an action state that calls a single operation.
              Hence, the name of the operation being called 
              is put in the symbol, 
              along with the name of the classifier that
              hosts the operation in parentheses under it.
              </para>

            </listitem>
            
            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/objectflowstate.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>ObjectFlowState</literal>. Add a objectflowstate to the 
              diagram.
              An objectflowstate is 
              an object that is input to or output from 
              an action.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Deployment Diagram Specific Tools</title>

          <para>Ten tools are provided specific to UML model elements on 
          deployment diagrams. The detailed properties of these 
          model elements are described in the section on deployment diagram 
          model elements (see <xref linkend="ch.ref.entdeploy"/>).</para>

          <note>

            <para>Remember that ArgoUML&apos;s deployment diagrams are 
            also used for component diagrams.</para>

          </note>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/node.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Node</literal>. Add a node to the diagram. For 
              convenience, when the mouse is over a selected node it 
              displays four handles to left, right, top and bottom 
              which may be dragged to form association 
              relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/node_instance.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Node Instance</literal>. Add a node instance to 
              the diagram. For convenience, when the mouse is over a 
              selected node instance it displays four handles to left, 
              right, top and bottom which may be dragged to form link 
              relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/component.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Component</literal>. Add a component to the 
              diagram. For convenience, when the mouse is over a 
              selected component it displays four handles to left, 
              right, top and bottom which may be dragged to form 
              dependency relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/component_instance.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Component Instance</literal>. Add a component 
              instance to the diagram. For convenience, when the mouse 
              is over a selected component instance it displays four 
              handles to left, right, top and bottom which may be 
              dragged to form dependency relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/generalization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Generalization</literal>. Add a generalization 
              between two model elements selected using button&nbsp;1 (from the 
              child to the parent).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/realization.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Realization</literal>. Add a realization between 
              a class and an interface selected using button&nbsp;1 motion 
              (from the realizing class to the realized 
              interface).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/dependency.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Dependency</literal>. Add a dependency between 
              two model elements selected using button&nbsp;1 motion (from the 
              dependent model element).</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_plain.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Association</literal>. Add an association 
              between two model elements (node, component, class or 
              interface) selected using button&nbsp;1 motion (from the first 
              model element to the second model element). There are 6 types of 
              association offered here, see 
              <xref linkend="fig.ref.edit_association_tools"/>: 
              <literal>association</literal>, <literal>
              aggregation</literal> and <literal>composition</literal>, 
              and all these three can be <literal>
              bidirectional</literal> or <literal>
              unidirectional</literal>.</para>

              <caution>

                <para>The constraint that associations between classes 
                and interfaces must not be navigable 
                <emphasis>from</emphasis> the interface still applies 
                on deployment diagrams.</para>

              </caution>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/object.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Object</literal>. Add an object to the diagram. 
              For convenience, when the mouse is over a selected object 
              it displays four handles to left, right, top and bottom, 
              which may be dragged to form link relationships.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/link.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Link</literal>. Add a link between two model elements 
              (node instance, component instance or object) selected 
              using button&nbsp;1 motion.</para>

            </listitem>

          </itemizedlist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.edit_pane_broom">

        <title>The Broom</title>

        <para>ArgoUML&apos;s broom alignment tool is specialized to 
        support the needs of designers in achieving the kind of 
        alignment used in UML diagrams. It is common for designers to 
        roughly align objects as they are created or by using simple 
        movement commands. The broom is an easy way to precisely align 
        objects that are already roughly aligned. Furthermore, the 
        broom&apos;s distribution options are suited to the needs of 
        UML designers: making related objects appear evenly spaced, 
        packing objects to save diagram space, and spreading objects 
        out to make room for new objects. The broom also makes it easy 
        to change from horizontal to vertical alignment or from 
        left-alignment to right-alignment.</para>

        <para>The T-shaped icon in ArgoUML&apos;s diagram toolbar 
        invokes the broom alignment tool. When the mouse button&nbsp;1 is 
        pressed while in broom-mode, the designer&apos;s initial mouse 
        movement orients the broom to face in one of four directions: 
        north, south, east, or west. After that, mouse drag events 
        cause the broom to advance in the chosen direction, withdraw, 
        or grow in a lateral direction. Like a real-world push broom, 
        the broom tool pushes diagram elements that come in contact 
        with it. This has the effect of aligning objects along the face 
        of the broom and provides immediate visual feedback (see the 
        figure below). Unlike a real-world broom, moving backwards 
        allows diagram elements to return to their original position. 
        Growing the broom makes it possible to align objects that are 
        not near each other. When the mouse button is released, the 
        broom disappears and the moved objects are selected to make it 
        easy to manipulate them further.</para>

        <figure float="1" id="fig.ref.editpane_broom">

          <title>The Broom.</title>

          <informaltable frame="none">

            <tgroup cols="2">

              <tbody>

                <row><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_broom1.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_broom2.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry></row>

                <row><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_broom3.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_broom4.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry></row>

              </tbody>

            </tgroup>

          </informaltable>

        </figure>

        <para>If the designer presses the <emphasis>space bar</emphasis> 
        while using the 
        broom, objects on the face of the broom are distributed (i.e., 
        spaced evenly). ArgoUML&apos;s broom supports three 
        distribution modes: objects can be spaced evenly across the 
        space that they use, objects can be packed together with only a 
        small gap between them, or objects can be distributed evenly 
        over the entire length of the broom&apos;s face. Repeatedly 
        pressing the space bar cycles among these three distribution 
        modes and displays a brief message indicating the operation 
        just performed: Space evenly, Pack tightly, Spread out and 
        Original.</para>
        
        <para>If the designer presses the <emphasis>Enter</emphasis> 
        key while using the broom,
        the broom turns red (instead of the normal blue), and objects are not
        picked up by the broom when moving forward. 
        It works like lifting up the broom. 
        Pressing Enter again returns to the normal mode.</para>
        
        <para>Pressing the <emphasis>Tab</emphasis>
        key works exactly like the Enter key.</para>

      </sect1>

      <sect1 id="s1.ref.edit_pane_selection_action_buttons">

        <title>Selection Action Buttons</title>

        <para>When the user selects a model element in a UML diagram, 
        several handles are drawn on it to indicate that it is selected 
        and to provide user interface affordances to resize the node. 
        ArgoUML also displays some <quote>selection-action 
        buttons</quote> around the selected model element. See the figure 
        below for some examples of the handles and 
        <quote>selection-action buttons</quote>. The two figures for a 
        class differ because for creating the second one, the shift key 
        has been depressed.</para>

        <figure float="1" id="fig.ref.editpane_selection_action_buttons">

          <title>Some examples of <quote>Selection Action 
          Buttons</quote>.</title>

          <informaltable frame="none">

            <tgroup cols="3">

              <tbody>

                <row><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons1.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons2.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons3.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry></row>

                <row><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons4.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons5.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry><entry><screenshot><mediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/reference/edit_selection_action_buttons6.png"
                 format="PNG"/></imageobject></mediaobject></screenshot></entry></row>

              </tbody>

            </tgroup>

          </informaltable>

        </figure>

        <para>Selection-action buttons offer common operations on the 
        selected object. For example, a class node has a button at 
        12-o&apos;clock for adding a superclass, one at 6-o&apos;clock 
        for adding a subclass, and buttons at 3-o&apos;clock and 
        9-o&apos;clock for adding associations. These buttons support a 
        &quot;click or drag&quot; interaction: a single click creates a 
        new related class at a default position relative to the 
        original class and creates a generalization or association; a 
        drag from the button to an existing class creates only the 
        generalization or association; and, a drag to an empty space in 
        the diagram creates a new class at the mouse position and the 
        generalization or association. ArgoUML provides some automated 
        layout support so that clicking the subclass button will 
        position the new classes so that they do not overlap.</para>

        <para>Selection-action buttons are transparent. They have a 
        visibly recognizable rectangular shape and size and they 
        contain an icon that is the same as the icon used for the 
        corresponding type of design element on the standard toolbar. 
        However, these icons are unfilled line drawings with many 
        transparent pixels. This allows selection-action buttons to be 
        overlaid onto the drawing area without overly obscuring the 
        diagram itself. Also, the buttons are only drawn when the mouse 
        is over the selected model element; if any part of the diagram is 
        obscured, the mouse can simply be moved away to get a clearer 
        view of the diagram.</para>

      </sect1>

      <sect1>

        <title>Clarifiers</title>

        <para>A key feature of ArgoUML are the critics, which run in 
        parallel with the main ArgoUML tool. When they find a problem, 
        they typically raise a to-do item, and also highlight the 
        problem on the editing pane. The graphical techniques used for 
        highlighting are called <emphasis>Clarifiers</emphasis></para>

        <itemizedlist>

          <listitem>

            <para>Note icon (<guiicon><inlinemediaobject><imageobject>
            <imagedata align="center" fileref="images/icons/note.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon>). 
            Displayed at the top left of a model element indicates a critic 
            of that model element. Moving the mouse over the icon will pop 
            up the critic headline.</para>

          </listitem>

          <listitem>

            <para>Colored wavy line (
            <guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/wavy_line.png"
             format="PNG"/></imageobject></inlinemediaobject></guiicon>). 
            Used for critics specific to sub-components of graphical 
            model elements. For example to underline attributes with a 
            problem within a class.</para>

          </listitem>

          <listitem>

            <para>Solid colored line (
            <guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/solid_line.png"
             format="PNG"/></imageobject></inlinemediaobject></guiicon>). 
            Not seen in ordinary editing, but used when a to-do item is 
            highlighted from the to-do pane (see 
            <xref linkend="ch.ref.todopane"/>) by button&nbsp;1 double 
            click. The solid line is used to show all the model elements 
            affected by the critic, for example all stimuli that are 
            out of order.</para>

          </listitem>

        </itemizedlist>

      </sect1>

      <sect1>

        <title>The Drawing Grid</title>

        <para>The editing pane is provided with a background grid which 
        can be set in various styles or turned off altogether through 
        the menu (see <xref linkend="s2.ref.menu_adjust_grid"/>).</para>

        <para>Whatever grid is actually displayed, placement of items 
        on the diagram is always controlled by the setting for grid 
        snap, which ranges from 4 to 32 pixels (see 
        <xref linkend="s2.ref.menu_grid_snap"/>).</para>

      </sect1>

      <sect1>

        <title>The Diagram Tab</title>

        <para>At the bottom of the editing pane is a small tab labeled 
        as <literal>As Diagram</literal>. The concept is that a UML 
        diagram can be displayed in a number of ways, for example as a 
        graphical diagram or as a table. Each representation would have 
        its own tab and be selected by button&nbsp;1 click on the tab.</para>

        <para>Earlier versions of ArgoUML did implement a tabular 
        representation, but the current release only supports a diagram 
        representation, so this tab does not have any function.</para>

      </sect1>

      <sect1 id="s1.ref.edit_pane_pop_up">

        <title>Pop-Up Menus</title>

        <para>Within the editing pane, button&nbsp;2 click over a model element 
        will bring up a pop-up menu with a variable number of main 
        entries, many with a sub-menu.</para>

        <sect2>

          <title>Critiques</title>

          <para>This sub-menu gives list of all the critics that have 
          triggered for this model element. Selection of a menu entry causes 
          that entry to be highlighted in the to-do pane and its 
          detailed explanation to be placed in the <literal>
          ToDoItem</literal> tab of the details pane. A solid colored 
          line indicates the offending element.</para>

        </sect2>

        <sect2>

          <title>Ordering</title>

          <para>This menu controls the ordering of overlapping 
          model elements on the diagram. It is equivalent to the <literal>
          Reorder</literal> sub-menu of the <literal>Arrange</literal> 
          menu (see <xref linkend="s2.ref.menu_reorder"/>). There are 
          four entries.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/forward.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Forward</literal>. The selected model elements are 
              moved one step forward in the ordering hierarchy with 
              respect to other model elements they overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/backward.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Backward</literal>. The selected model elements are 
              moved one step back in the ordering hierarchy with 
              respect to other model elements they overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/to_front.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>To Front</literal>. The selected model elements are 
              moved to the front of any other model elements they 
              overlap.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/to_back.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>To Back</literal>. The selected model elements are 
              moved to the back of any other model elements they 
              overlap.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Add</title>

          <para>This sub-menu only appears for model elements that can have 
          notes attached (class, interface, object, state, pseudostate) 
          or have operations or attributes added (class, interface). 
          There are at most three entries.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Attribute</literal>. Only appears where the 
              selected model element is a class. Creates a new attribute on 
              the model element.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Operation</literal>. Only appears where the 
              selected model element is a class or interface. Creates a new 
              operation on the model element.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/note.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Comment</literal>. Attaches a new comment to 
              the selected model element.</para>

            </listitem>

            <listitem>

              <para><literal>Add All Relations</literal>. 
              Only appears where the 
              selected model element is a class or interface. 
              Makes all relations visible that exist in the model and
              that are connected to the selected model element.
              </para>

            </listitem>

            <listitem>

              <para><literal>Remove all Relations</literal>. 
              Only appears where the 
              selected model element is a class or interface.
              Removes all connected relations from the diagram 
              (without removing them from the model).
              </para>

            </listitem>
          </itemizedlist>

        </sect2>

        <sect2>

          <title>Show</title>

          <para>This sub-menu only appears with certain model elements. It 
          is completely context dependent. There are many possible 
          entries, depending on the selected model element and its 
          state.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Hide Extension Point 
              Compartment</literal>. Only appears when the extension 
              point compartment of a use case is displayed. Hides the 
              compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Show Extension Point 
              Compartment</literal>. Only appears when the extension 
              point compartment of a use case is hidden. Displays the 
              compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Hide All Compartments</literal>. Only 
              appears when both attribute and operation compartments 
              are displayed on a class or object. Hides both 
              compartments.</para>

            </listitem>

            <listitem>

              <para><literal>Show All Compartments</literal>. Only 
              appears when both attribute and operation compartments 
              are hidden on a class or object. Displays both 
              compartments.</para>

            </listitem>

            <listitem>

              <para><literal>Hide Attribute Compartment</literal>. Only 
              appears when the attribute compartment of a class or 
              object is displayed. Hides the compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Show Attribute Compartment</literal>. Only 
              appears when the attribute compartment of a class or 
              object is hidden. Displays the compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Hide Operation Compartment</literal>. Only 
              appears when the operation compartment of a class or 
              object is displayed. Hides the compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Show Operation Compartment</literal>. Only 
              appears when the operation compartment of a class or 
              object is hidden. Displays the compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Hide Enumeration Literal Compartment</literal>. Only 
              appears when the enumeration literal compartment 
              of an enumeration 
              is displayed. Hides the compartment.</para>

            </listitem>

            <listitem>

              <para><literal>Show Enumeration Literal Compartment</literal>. Only 
              appears when the enumeration literal compartment of an enumeration
              is hidden. Displays the compartment.</para>

            </listitem>
            
            <listitem>

              <para><literal>Show All Edges</literal>. Only appears on 
              a class. Displays all associations (to shown model elements) 
              that are not shown yet. This is the same function as the 
              &quot;add to Diagram&quot; on the asociation in the 
              explorer context menu. currently.</para>

            </listitem>

            <listitem>

              <para><literal>Hide All Edges</literal>. Only appears on 
              a class. Hides all associations. This is the same 
              function as <quote>Remove from Diagram</quote> on all the 
              associations of this class.</para>

            </listitem>

            <listitem>

              <para><literal>Hide Stereotype</literal>. Only appears 
              when the Stereotype of a package is displayed. Hides the 
              stereotype.</para>

            </listitem>

            <listitem>

              <para><literal>Show Stereotype</literal>. Only appears 
              when the Stereotype of a package is hidden. Displays the 
              stereotype.</para>

            </listitem>

            <listitem>

              <para><literal>Hide Visibility</literal>. Only appears 
              when the visibility of a package is displayed. Hides the 
              visibility.</para>

            </listitem>

            <listitem>

              <para><literal>Show Visibility</literal>. Only appears 
              when the visibility of a package is hidden. Displays the 
              visibility.</para>

            </listitem>
          </itemizedlist>

        </sect2>

        <sect2>

          <title>Modifiers</title>

          <para>This sub-menu only appears with class, interface, 
          package and use case model elements. It is used to set or clear 
          the values of the various modifiers available.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Abstract</literal>. Set for an abstract 
              model element.</para>

            </listitem>

            <listitem>

              <para><literal>Leaf</literal>. Set for a final model element, 
              i.e. one with no sub-model elements.</para>

            </listitem>

            <listitem>

              <para><literal>Root</literal>. Set for a root model element, 
              i.e. one with no super-model elements.</para>

            </listitem>

            <listitem>

              <para><literal>Active</literal>. Set for a model element with 
              dynamic behavior.</para>

              <note>

                <para>This really ought to be set automatically for 
                model elements with state machines or activity 
                diagrams.</para>

              </note>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Multiplicity</title>

          <para>This sub-menu only appears with association model elements, 
          when clicking at one end of the association. It is used to 
          control the multiplicity at the end of the association 
          nearest the mouse click point. There are only four entries, a 
          sub-set of the range of multiplicities that are available 
          through the property sheet of a association end (see 
          <xref linkend="s1.ref.association_end_use_case"/>).</para>

          <itemizedlist>

            <listitem>

              <para><literal>1</literal></para>

            </listitem>

            <listitem>

              <para><literal>0..1</literal></para>

            </listitem>

            <listitem>

              <para><literal>1..*</literal></para>

            </listitem>

            <listitem>

              <para><literal>0..*</literal></para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Aggregation</title>

          <para>This sub-menu only appears with association model elements, 
          when clicking at one end of the association. It is used to 
          control the aggregation at the end of the association nearest 
          the mouse click point. There are three entries.</para>

          <itemizedlist>

            <listitem>

              <para><literal>none</literal>. Remove any 
              aggregation.</para>

            </listitem>

            <listitem>

              <para><literal>aggregate</literal>. Make this end a 
              shared aggregation (loosely known as an 
              <quote>aggregation</quote>).</para>

            </listitem>

            <listitem>

              <para><literal>composite</literal>. Make this end a 
              composite aggregation (loosely known as a 
              <quote>composition</quote>).</para>

            </listitem>

          </itemizedlist>

          <caution>

            <para>UML requires that an end with a composition 
            relationship must have a multiplicity of 1 (the 
            default).</para>

          </caution>

        </sect2>

        <sect2>

          <title>Navigability</title>

          <para>This sub-menu only appears with association model elements, 
          when clicking at one end of the association. It is used to 
          control the navigability of the association. There are three 
          entries.</para>

          <itemizedlist>

            <listitem>

              <para><literal>bidirectional</literal>. Make the 
              association navigable in both directions.</para>

            </listitem>

            <listitem>

              <para><literal>&lt;class1&gt; to 
              &lt;class2&gt;</literal>. Make the association navigable 
              only from &lt;class1&gt; to &lt;class2&gt;. In other 
              words &lt;class1&gt; can reference &lt;class2&gt; but not 
              the other way round.</para>

            </listitem>

            <listitem>

              <para><literal>&lt;class2&gt; to 
              &lt;class1&gt;</literal>. Make the association navigable 
              only from &lt;class2&gt; to &lt;class1&gt;. In other 
              words &lt;class2&gt; can reference &lt;class1&gt; but not 
              the other way round.</para>

            </listitem>

          </itemizedlist>

          <note>

            <para>UML does permit an association to be non-navigable in 
            both directions. ArgoUML will allow this, but you will have 
            to set each of the association ends navigation property, 
            reached from the property tab of the association - and the 
            diagram does not show any arrows in this case.</para>

            <para>This is considered bad design practice (it will 
            trigger a critic in ArgoUML), so is only of theoretical 
            interest.</para>

          </note>

          <note>

            <para>UML does not permit navigability from an interface to 
            a class. ArgoUML does not prevent this.</para>

          </note>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.notation">

        <title>Notation</title>

        <para>Notation is the textual representation 
        on the diagram of a modelelement or its properties.
        </para>

        <sect2>
        <title>Notation Languages</title>
        <para>ArgoUML supports showing notation in different languages.
        By default, all text is shown in UML notation, 
        but the menus contain an item to select between
        Java and UML.
        With plugin modules, 
        it is even possible to select other languages, 
        such as C++.
        </para>
        
        <para><xref linkend="fig.ref.notation_uml"/>
        shows a class in UML notation, while
        <xref linkend="fig.ref.notation_java"/>
        shows the same class in Java notation. 
        </para>

        <figure float="1" id="fig.ref.notation_uml">

          <title>A class in UML notation</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/notation_uml.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>
        
        <figure float="1" id="fig.ref.notation_java">

          <title>A class in Java notation</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/notation_java.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        </sect2>

        <sect2>
        <title>Notation Editing on the diagram</title>

        <para>Most text shown on a diagram may be edited by
        double-clicking button&nbsp;1 on the text. 
        This causes a edit box to be shown, 
        with the previous text selected,
        ready for amending.</para>

        <para>Also, the status bar of ArgoUML 
        (i.e. the small area at the bottom of the ArgoUML window),
        shows an help text that indicates the syntax of the text to be entered.
        Text entry can be concluded by pressing F2, 
        or for single-line fields, by pressing the enter key.
        Additionally, editing can be concluded by 
        clicking somewhere in the diagram outside the edit area.
        </para>
        
        <para>Editing notation on the diagram is a very powerful way
        to enter a lot of model-information in a very compact way. 
        It is e.g. possible to create an operation, 
        its stereotype,
        all parameters and their types, 
        and operation properties (visibility, concurrency), all
        at once by typing:</para>
        
        <programlisting>+Order(customerID : int,items : List) : void {sequential}</programlisting>
        
        <para>An association (e.g. between two classes) is showing many
        texts close to its middle and ends, 
        so it deserves some extra explanation.
        <xref linkend="fig.ref.notation_association"/> shows two associations
        to clarify the following:
        </para>

        <figure float="1" id="fig.ref.notation_association">

          <title>A couple of associations with adornments</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/notation_association.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>        

        <para>The association on the right shows that 
        invisible fields where text can be entered
        become visible once the modelelement is selected.
        The fields are indicated by blue rectangles - 
        double-click on them with mouse button&nbsp;1 to start editing.</para>
        
        <para>The visibility (the +, -, # or ~) is shown 
        together with the association-end name, 
        but it is not shown 
        for an unnamed association end.</para>
        
        <para>Likewise, the multiplicity is not shown if it is 1, 
        unless the setting 
        <literal>Show "1" multiplicities</literal>
        in the menu 
        <literal>File=&gt;Properties</literal>
        is checked.</para>
        
        <para>The example figure does not demonstrate this, but 
        stereotypes of an association are shown on the diagram, 
        but are not editable. 
        And stereotypes of association-ends are shown
        together with the association-end name.
        </para>
        
        </sect2>

        <sect2>
        <title>Notation Parsing</title>
        <para>(to be written)</para>
        <!-- TODO: Describe all Notation providers' syntax. -->
        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.detpane">

      <title>The Details Pane</title>

      <sect1>

        <title>Introduction</title>

        <para><xref linkend="fig.ref.details_pane"/> shows the ArgoUML 
        window, with the details pane highlighted.</para>

        <figure float="1" id="fig.ref.details_pane">

          <title>Overview of the details pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_pane.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>For any model element within the system, this pane is where 
        all its associated data is viewed and entered.</para>

        <para>The Pane has a series of tabs at the top, which are 
        selected by button&nbsp;1 click The body of a tab is a menu of items 
        to be checked, selected or entered specific to the particular 
        tab selected.</para>

        <para>Of these, the <literal>Properties</literal> Tab is by far 
        the most complex, with a different presentation for each 
        model element within the system. The detailed descriptions of the 
        properties tab for each model element are the subject of separate 
        chapters covering the model elements that may appear on the various 
        diagrams (see <xref linkend="ch.ref.entities"/> through 
        <xref linkend="ch.ref.entdeploy"/>).</para>

      </sect1>

      <sect1 id="s1.ref.to_do">

        <title>To Do Item Tab</title>

        <para>This tab provides control over the various to-do items 
        created by the user, or raised automatically by the ArgoUML 
        critics (discussed in more detail in the section on the 
        <literal>Critique</literal> menu&mdash;see 
        <xref linkend="s1.ref.menu_critique"/>). 
        <xref linkend="fig.ref.details_to_do"/> shows a typical pane. 
        The to-do item is selected with button&nbsp;1 in the to-do pane (see 
        <xref linkend="ch.ref.todopane"/>) or by using the <literal>
        Critiques</literal> context sensitive pop-up menu on the 
        editing pane.</para>

        <figure float="1" id="fig.ref.details_to_do">

          <title>Example of the <literal>To Do Item</literal> tab on 
          the properties pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_to_do.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>Customization of the critics behaviour is possible 
        through the <literal>Browse critics...</literal> menu (see 
        <xref linkend="s2.ref.menu_browse_critics"/>).</para>

        <para>The body of the tab describes the problem found by the 
        critic and outlines how it can be fixed. To the left are four 
        buttons.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/new_to_do_item.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New To Do Item...</literal> This launches a dialog 
            box (see <xref linkend="fig.ref.details_new_to_do"/>), 
            which allows you to create your own to-do item, with its 
            own headline (which appears in the to-do pane), priority 
            for the to-do pane, reference URL and detailed description 
            for further information.</para>

            <figure float="1" id="fig.ref.details_new_to_do">

              <title>Dialog box for <literal>
              New To Do Item</literal></title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/details_new_to_do.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/resolve_item.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Resolve Item...</literal> This pops up a dialog 
            allowing the user to resolve the selected to-do item (see 
            <xref linkend="fig.ref.details_resolve_to_do"/>). This is 
            an important dialog, because it allows you to deal with 
            to-do items in ways other than the recommendation of the 
            to-do item (which is the whole point of their being 
            advisory).</para>

            <para>This dialog box is intended to be used for the 
            following reasons: deleting todo items that were manually 
            created, preventing a single critic to trigger on a single 
            object, and dismissing categories of todo items by lowering 
            design concerns or design goals.</para>

            <figure float="1" id="fig.ref.details_resolve_to_do">

              <title>Dialog box for <literal>
              Resolve Item</literal></title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/details_resolve_to_do.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>At the top are three radio-buttons, of which by 
            default the last is selected, labeled 1) <literal>It is not 
            relevant to my goals</literal>, 2) <literal>It is not of 
            concern at the moment</literal>, and 3) <literal>Reason 
            given below</literal>. If you choose the third of these you 
            should enter a reason in the main text box.</para>

            <tip>

              <para>If you wish to resolve a to-do item (that is 
              generated by a critic) by following its recommendations, 
              just make the recommended changes and the to-do item will 
              disappear of its own accord. There is no need to use this 
              dialog.</para>

            </tip>

            <warning>

              <para>The V0.20 version of ArgoUML implementation is 
              incomplete: The reason given is not stored when the 
              project is saved. And there is no way to retrieve todo 
              items that were resolved. So, it is not usefull to give a 
              reason at all.</para>

              <para>When a todo item generated by a critic is resolved, 
              then there is no way to undo this (unless by re-creating 
              the object that triggered the critic).</para>

            </warning>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/snooze_critic.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Snooze Critic</literal> This suspends the activity 
            of the critic that generated the current to-do item. The 
            to-do item (and all others generated by the critic) will 
            disappear from the to-do pane.</para>

            <para>The critic will wake up after a period of time. 
            Initially this period is 10 minutes, but it doubles on each 
            successive application of the Snooze button. The critic can 
            be awakened explicitly through the <literal>
            Critique &gt; Browse Critics...</literal> menu (see 
            <xref linkend="s2.ref.menu_browse_critics"/>).</para>

            <tip>

              <para>Some common critics can fire the whole time as you 
              build a big diagram. Some users find it useful to snooze 
              these critics until the diagram has been completed.</para>

            </tip>

          </listitem>

        </itemizedlist>

        <sect2>

          <title>Wizards</title>

          <para>Some of the more common critics have a 
          <quote>wizard</quote> available to help in fixing the 
          problem. The wizard comprises a series of pages (one or more) 
          in the <literal>ToDo Item</literal> tab that step you through 
          the changes. Start the wizard by clicking the 
          <literal>Next&gt;</literal> button.
          </para>

          <figure float="1" id="fig.ref.details_wizard">

            <title>Example of a <literal>Wizard</literal></title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/details_wizard.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>The wizard is driven through the first three buttons at 
          the bottom of the <literal>ToDo Item</literal> tab.</para>

          <itemizedlist>

            <listitem>

              <para><literal>&lt;Back</literal>. This will take you back to 
              the previous step in the wizard. Grayed out if this is 
              the first step.</para>

            </listitem>

            <listitem>

              <para><literal>Next&gt;</literal>. This will take you back to 
              the next step in the wizard. Grayed out if this is the 
              last step.</para>

            </listitem>

            <listitem>

              <para><literal>Finish</literal>. This will commit the 
              changes you have made through the wizard in previous 
              steps, and/or use the defaults for all next steps.</para>

            </listitem>

          </itemizedlist>

          <note>

            <para>Not all to-do items have wizards. If there is no 
            wizard all three buttons will remain grayed out.</para>

          </note>
          
          <para>
          The ArgoUML wizards are <emphasis>non-modal</emphasis>, i.e. 
          once started, you may select other todo items, 
          or do some other actions, and all the while the wizard will
          remeber where it was, so if you return to the todo item,
          the wizard will indicate the same step it was on when you left it.
          </para>

        </sect2>

        <sect2>

          <title>The Help Button</title>

          <para>There is one remaining button at the bottom of the 
          <literal>To Do Item</literal> tab, labeled <literal>
          Help</literal>. This will fire up a browser to a URL with 
          further help.</para>

          <!--warning>

            <para>In the V0.20 release of ArgoUML the URLs are 
            generally invalid. The few that are valid have no 
            information.</para>

          </warning-->

        </sect2>

      </sect1>

      <sect1 id="s1.ref.proptab">

        <title>Properties Tab</title>

        <para>Through this tab, the properties of model elements selected in 
        the explorer or editing pane may be set. The properties of an 
        model element may be displayed in one of the following ways:</para>

        <orderedlist>

          <listitem>

            <para>Selection of the model element in the explorer or editing 
            panes, followed by selection of the properties tab in the 
            details pane; or</para>

          </listitem>

          <listitem>

            <para>Navigation buttons cause different model elements to be 
            selected. I.e. the <literal>Go Up</literal> button on the 
            properties tab, the <literal>Navigate Back</literal> and 
            <literal>Navigate Forward</literal> buttons in the main 
            tool bar, and the various menu-items under <literal>Edit - 
            Select</literal>.</para>

          </listitem>

        </orderedlist>

        <para><xref linkend="fig.ref.details_properties"/> shows a 
        typical properties tab for a model element in ArgoUML (in this case 
        a class).</para>

        <figure float="1" id="fig.ref.details_properties">

          <title>A typical <literal>Properties</literal> tab on the 
          details pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_properties.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>At the top left is the icon and name of the type of 
        model element (i.e. the UML metaclass, not the actual name of this 
        particular model element). In this example the property tab is for a 
        class.</para>

        <para>To the right of this is a toolbar of icons relevant to 
        this property tab. The first one is always navigation <literal>
        Go up</literal>. The last is always <literal>Delete</literal> 
        to delete the selected model element from the model. The ones in 
        between depend on the model element.</para>

        <para>The remainder of the tab comprises fields, laid out in 
        two or three columns. Each field has a label to its left. The 
        fields may be text boxes, text areas, drop down selectors, 
        radio boxes and check boxes. In most (but not all cases) the 
        values can be changed. In the case of text boxes this is 
        sometimes by just typing the required value.</para>

        <para>However for many text boxes and text areas, data entry is 
        via a context sensitive pop-up menu (using button&nbsp;2 click), 
        which offers options to add a new entry, delete an entry or 
        move entries up and down (in text areas with multiple 
        entries).</para>

        <para>The first field is almost always a text field <literal>
        Name</literal>, where the name of the specific model element can be 
        entered. The remaining fields vary depending on the model element 
        selected.</para>

        <para>The detailed property sheets for all ArgoUML model elements 
        are discussed in separate chapters for each of the diagram 
        types (use case diagram (<xref linkend="ch.ref.entusecase"/>, 
        class diagram (<xref linkend="ch.ref.entclass"/>, sequence 
        diagram (<xref linkend="ch.ref.entseq"/>, statechart diagram (
        <xref linkend="ch.ref.entstate"/>, collaboration diagram (
        <xref linkend="ch.ref.entcollab"/>, activity diagram (
        <xref linkend="ch.ref.entactiv"/>, deployment diagram (
        <xref linkend="ch.ref.entdeploy"/>). Property sheets for 
        model elements that are common to all diagram types have their own 
        chapter (<xref linkend="ch.ref.entities"/>).</para>

        <caution>

          <para>ArgoUML will always try to squeeze all fields on to the 
          property sheet. If the size of the property tab is too small, 
          it may become unusable. The solution is to either enlarge the 
          property tab by enlarging the main window, or by moving the 
          dividers to left and top.</para>

        </caution>

      </sect1>

      <sect1 id="s2.ref.documentation_tab">

        <title>Documentation Tab</title>

        <para>Within the UML&nbsp;1.4 standard, all model elements are children 
        of the <literal>Element</literal> metaclass. The <literal>
        Element</literal> metaclass defines a tagged value <literal>
        documentation</literal> for comment, description or explanation 
        of the element to which it is attached. Since this tagged value 
        applies to every model element, it is given its own tab in the 
        details pane, rather than being part of the <literal>
        Tagged Values</literal> tab.</para>

        <para><xref linkend="fig.ref.details_documentation"/> shows a 
        typical documentation tab for a model element in ArgoUML.</para>

        <figure float="1" id="fig.ref.details_documentation">

          <title>A typical <literal>Documentation</literal> tab on the 
          details pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_documentation.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>As you can see, many more fields have been added 
        to the Documentation field alone. The other fields 
        similarly store their information under tagged values:
        <literal>author</literal>,
        <literal>version</literal>, 
        <literal>since</literal>, 
        <literal>deprecated</literal>, 
        <literal>see</literal>.
        </para>
        
        <para>The fields on this tab are the same for all 
        model elements.</para>

        <para>Since UML comments are a kind of documentation, 
        they are also shown on this tab, with name and body.</para>

        <itemizedlist>

          <listitem>

            <para><literal>Author:</literal> A text box for the author 
            of the documentation.</para>

          </listitem>

          <listitem>

            <para><literal>Version:</literal> A text box for the 
            version of the documentation.</para>

          </listitem>

          <listitem>

            <para><literal>Since:</literal> A text box to show how long 
            the documentation has been valid.</para>

          </listitem>

          <listitem>

            <para><literal>Deprecated:</literal> A check box to 
            indicate whether this model element is deprecated (i.e. planned 
            for removal in future versions of the design model).</para>

          </listitem>

          <listitem>

            <para><literal>See:</literal> Pointers to documentation 
            outside the system.</para>

          </listitem>

          <listitem>

            <para><literal>Documentation:</literal> Literal text of any 
            documentation.</para>

          </listitem>

          <listitem>

            <para><literal>Comment Name:</literal> 
            The names of all comments attached to the modelelement.
            </para>

          </listitem>
          
          <listitem>

            <para><literal>Body:</literal> 
            The bodies of all comments attached to this modelelement.
            </para>

          </listitem>
          
        </itemizedlist>

        <tip>

          <para>ArgoUML is not primarily a documentation system. For 
          model elements that require heavy documentation, notably use 
          cases, the use of the <literal>See:</literal> field to point 
          to external documents is more practical.</para>

        </tip>

      </sect1>

      <sect1>

        <title>Presentation Tab</title>

        <para>This tab provides some limited control over the graphical 
        representation of model elements in the diagram in the editing 
        pane.</para>

        <para>Model elements that do not have any specific direct graphical 
        representation on the screen (beyond their textual description) 
        do not have style tabs of their own. For example the style 
        sheet of an operation on a class will be downlighted.</para>

        <para>Style sheets vary a little from model element to model element, but 
        <xref linkend="fig.ref.details_style"/> shows a typical style 
        tab for a model element in ArgoUML (in this case a class).</para>

        <figure float="1" id="fig.ref.details_style">

          <title>A typical <literal>Presentation</literal> tab on the 
          details pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_style.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>There may be further fields in some cases, e.g. for a 
        package, but most fields are common to many model elements.</para>

        <itemizedlist>

          <listitem>
            <para><literal>Path</literal>
              This checkbox allow to display or hide the path  
              in front of the name of the modelelement. 
              It is shown in UML notation with <literal>::</literal>
              seperators. E.g. the ArgoUML Main class would be shown as: 
              <literal>org::argouml::application::Main</literal>.
            </para>
          </listitem>

          <listitem>
            <para><literal>Attributes</literal>
            This checkbox allows to hide or show the attributes compartment of 
            a class.
            </para>
          </listitem>

          <listitem>
            <para><literal>Operation</literal>
            This checkbox allows to hide or show the operations compartment of 
            a class or interface.
            </para>
          </listitem>

          <listitem>
            <para><literal>Stereotype</literal>
            This checkbox allows to reveal or hide the stereotypes of 
            a package, shown above the name.
            </para>
          </listitem>

          <listitem>
            <para><literal>Visibility</literal>
            This checkbox allows to hide the visibility of 
            a package. 
            The visibility is shown in UML notation as +, -, # or ~.
            </para>
          </listitem>

          <listitem>
            <para><literal>Extension Points</literal>
            This checkbox allows to reveal or hide 
            the extensions points compartment of 
            a usecase.
            </para>
          </listitem>

          <listitem>
            <para><literal>Bounds:</literal> This defines the corners 
            of the bounding box for a 2D model element. It comprises four 
            numbers separated by commas. These four numbers are 
            respectively: i) the X coordinate of the upper left corner 
            of the box; ii) the Y coordinate of the upper left corner 
            of the box; iii) the width of the box; and iv) the height 
            of the box. All units are pixels on the editing pane.</para>

            <para>This field has no effect on 1D model elements that link 
            other model elements (associations, generalizations etc), since 
            their position is constrained by their connectedness. In 
            this case the field is downlighted.</para>

          </listitem>

          <listitem>

            <para><literal>Fill:</literal> This drop-down selector 
            specifies the fill color for 2D model elements. It is not 
            present for line model elements. Selecting <literal>No 
            Fill</literal> makes the model element transparant. Selecting 
            <literal>Custom</literal> allows to create other colors 
            then the ones listed. It causes the color selector dialog 
            box to appear, see 
            <xref linkend="fig.ref.details_style_colorpicker1"/>.</para>

          </listitem>

          <listitem>

            <para><literal>Line:</literal> This drop-down selector 
            specifies the line color for model elements. Selecting <literal>
            No Fill</literal> makes the model element transparant. Selecting 
            <literal>Custom</literal> allows to create other colors 
            then the ones listed. It causes the color selector dialog 
            box to appear, see 
            <xref linkend="fig.ref.details_style_colorpicker1"/>.</para>

          </listitem>

        </itemizedlist>

        <figure float="1" id="fig.ref.details_style_colorpicker1">

          <title>The <literal>Custom Fill/Line Color</literal> dialog 
          box</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_style_colorpicker1.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <figure float="1" id="fig.ref.details_style_colorpicker2">

          <title>The <literal>Custom Fill/Line Color</literal> dialog 
          box</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_style_colorpicker2.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <figure float="1" id="fig.ref.details_style_colorpicker3">

          <title>The <literal>Custom Fill/Line Color</literal> dialog 
          box</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_style_colorpicker3.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

      </sect1>

      <sect1>

        <title>Source Tab</title>

        <para>This tab shows the source code that 
        will be generated for this model element, in the selected language. 
        ArgoUML generates the code e.g. for classes and interfaces. 
        The code shown here, may be saved in the indicated files 
        with the aid of the functions in the Generation menu.
        </para>

        <figure float="1" id="fig.ref.details_source">

          <title>The Source Tab of a class.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_source.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>
        
        <para>Any code you add will be lost - that 
        is not the intention of ArgoUML - use an IDE instead.
        </para>
        
        <para>The dropdown at the right allows selection of the output file. 
        This function is not very useful for languages 
        that generate all code for a class within one file,
        but serves its purpose for e.g. C++, where a .h and .cpp file
        are generated. See the figure below.</para>
         
        <figure float="1" id="fig.ref.details_source_cpp">

          <title>A C++ example.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_source_cpp.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>
        
      </sect1>

      <sect1 id="s1.ref.details_constraints">

        <title>Constraints Tab</title>

        <para>Constraints are one of the extension mechanisms provided 
        for UML. ArgoUML is equipped with a powerful constraint editor 
        based on the <emphasis>Object Constraint Language 
        (OCL)</emphasis> defined in the UML&nbsp;1.4 standard.</para>

        <caution>

          <para>The OCL editor implementation for ArgoUML V0.26 
          doesn&apos;t support OCL constraints for elements other than 
          Classes and Features.</para>

          <para>This is something of a general restriction of OCL. 
          Although the UML specification claims that there may be a 
          constraint for every model element, the OCL specification 
          only defines classes/interfaces and operations as allowable 
          contexts.</para>

          <para>It is not before OCL 2.0 that a more general definition 
          of allowable contexts is introduced. The key issue is that 
          for each context definition you need to define what is the 
          contextualClassifier, i.e., the classifier that will be 
          associated with the self keyword. The creators of the OCL 
          specification claim that this is not an issue for the OCL 
          specification, but rather for UML or some integration task 
          force. Conversely, it seems that the UML specification people 
          seem to expect this to be defined in the OCL specification 
          (which is why we did a first step in that direction in OCL 
          2.0).</para>

          <para>So, to cut a long story short, it appeared that the 
          simplest solution for ArgoUML at the moment would be to 
          enable the OCL property panel only for those model elements 
          for which there actually exists a definition of the 
          contextualClassifier in OCL 1.4. These are (s. above) 
          Class/Interface and Feature.</para>

        </caution>

        <para>The standard pre-defines a small number of constraints 
        (for example the <literal>xor</literal> constraint over a set 
        of associations indicating that only one may be manifest for 
        any particular instance).</para>

        <para>The standard also envisages a number of circumstances 
        where general purpose constraints may be useful:</para>

        <itemizedlist>

          <listitem>

            <para>To specify invariants on classes and types in the 
            class model;</para>

          </listitem>

          <listitem>

            <para>To specify type invariants for stereotypes;</para>

          </listitem>

          <listitem>

            <para>To describe pre-conditions and post-conditions on operations 
            and methods;</para>

          </listitem>

          <listitem>

            <para>To describe guards;</para>

          </listitem>

          <listitem>

            <para>As a navigation language; and</para>

          </listitem>

          <listitem>

            <para>To specify constraints on operations.</para>

          </listitem>

        </itemizedlist>

        <para><xref linkend="fig.ref.details_constraints"/> shows a 
        typical constraint tab for a model element in ArgoUML (in this case 
        a class).</para>

        <figure float="1" id="fig.ref.details_constraints">

          <title>A typical <literal>Constraints</literal> tab on the 
          details pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/details_constraints.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>Along the top of the tab are a series of icons.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/new_constraint.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Constraint</literal>. This creates a new 
            constraint and launches the constraint editor in the 
            <literal>Constraints tab</literal> for that new constraint 
            (see <xref linkend="s2.ref.details_constraint_editor"/>). 
            The new constraint is created with a context declaration 
            for the currently selected model element.</para>

            <warning>

              <para>It seems logical, that when a new constraint is 
              created, it needs to be edited. But ArgoUML V0.26 fails 
              to start the OCL editor upon creation; you have to do 
              this by primo selecting the new constraint first, secundo 
              rename it, and tertio press the <literal>Edit 
              Constraint</literal> button. It is essental for 
              successfully creating a constraint to follow these 4 
              steps accurately: create, select, rename, edit. The step 
              to rename is necessary, because the validity check will 
              refuse the constraint if its name differs from the name 
              mentioned in the constraint text. For the same reason, 
              renaming a constraint afterwards is impossible.</para>

            </warning>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/delete_constraint.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Delete Constraint</literal>. The constraint 
            currently selected in the <literal>
            Constraint Name</literal> box (see below) is deleted.</para>

            <caution>

              <para>In V0.26 of ArgoUML this button is not downlighted 
              when it is not functional, i.e. when no constraint is 
              selected.</para>

            </caution>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/edit_constraint.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Edit Constraint</literal>. This launches the 
            constraint editor in the <literal>Constraints</literal> tab 
            (see <xref linkend="s2.ref.details_constraint_editor"/>). 
            The editor is invoked on the constraint currently selected 
            in the <literal>Constraint Name</literal> box.</para>

            <caution>

              <para>In V0.26 of ArgoUML this button is not downlighted 
              when it is not functional, i.e. when no constraint is 
              selected.</para>

            </caution>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/configure_constraints.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Configure Constraint Editor</literal>. This a 
            dialog to configure options in the constraint editor (see 
            <xref linkend="fig.ref.details_constraints_dialog"/>
            ).</para>

            <figure float="1" id="fig.ref.details_constraints_dialog">

              <title>Dialog box for configuring constraints</title>

              <screenshot><mediaobject><imageobject>
              <imagedata align="center"
               fileref="images/reference/details_constraints_dialog.png"
               format="PNG"/></imageobject></mediaobject></screenshot>
            </figure>

            <para>The dialog box has a check box for the following 
            option.</para>

            <itemizedlist>

              <listitem>

                <para><literal>Check type conformance of OCL 
                constraints</literal>. OCL is strictly typed. At the 
                early stages of design it may be helpful to disable 
                type checking, rather than follow through all the 
                detailed specification needed to get type 
                consistency.</para>

              </listitem>

            </itemizedlist>

            <para>At the bottom are two buttons, labeled <literal>
            OK</literal> (to accept the option changes) and <literal>
            Cancel</literal> (to discard the changes).</para>

          </listitem>

        </itemizedlist>

        <para>The main body of the constraints tab comprises two boxes, 
        a smaller to the left and a larger one to the right. The two 
        are separated by two small arrow buttons which control the size 
        of the boxes.</para>

        <itemizedlist>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/constraints_left.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Shrink Left</literal>. Button&nbsp;1 click on this icon 
            shrinks the box on the left. Its effect may be reversed by 
            use of the <literal>Shrink Right</literal> button (see 
            below).</para>

          </listitem>

          <listitem>

            <para><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/constraints_right.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>Shrink Right</literal>. Button&nbsp;1 click on this 
            icon shrinks the box on the right. Its effect may be 
            reversed by use of the <literal>Shrink Left</literal> 
            button (see above).</para>

          </listitem>

        </itemizedlist>

        <para>Finer control can be achieved by using button&nbsp;1 motion to 
        drag the dividing bar to left and right.</para>

        <para>The box on the left is titled <literal>Constraint 
        Name</literal> and lists all the constraints (if any) so far 
        defined for the selected model element. A constraint may be selected 
        by button&nbsp;1 click.</para>

        <para>The box on the right is labeled <literal>
        Preview</literal> and contains the text of the constraint. This 
        box only shows some contents if a constraint is selected. Where 
        a constraint is too large for the box, a scroll bar is provided 
        to the right.</para>

        <sect2 id="s2.ref.details_constraint_editor">

          <title>The Constraint Editor</title>

          <para>This is invoked through the use of the <literal>
          Edit Constraint</literal> button on the main <literal>
          Constraints</literal> tab. The constraint editor takes up the 
          whole tab (see 
          <xref linkend="fig.ref.details_constraint_editor"/>).</para>

          <figure float="1" id="fig.ref.details_constraint_editor">

            <title>Dialog box for configuring constraints</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/details_constraint_editor.png"
             format="PNG"/></imageobject></mediaobject></screenshot>
          </figure>

          <para>Along the top of the tab are a series of icons.</para>

          <itemizedlist>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/cancel_edit_constraint.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Cancel Edit Constraint</literal>. This exits the 
              constraint editor without saving any changes and returns 
              to the main <literal>Constraints</literal> tab.</para>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/check_constraint.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Check OCL Syntax</literal>. This button invokes 
              a full syntax check of the OCL written in the editor. If 
              the syntax is valid, the constraint is saved, and control 
              returns to the main <literal>Constraints</literal> tab. 
              If the syntax is not valid, a dialog box explains the 
              problem.</para>

              <warning>

                <para>Whether type checking is included should be 
                configurable with the <literal>
                Configure Constraint Editor</literal> button (see 
                below). But ArgoUML V0.20 does always check, and 
                refuses to accept any constraint with the slightest 
                error.</para>

              </warning>

            </listitem>

            <listitem>

              <para><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/configure_constraints.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Configure Constraint Editor</literal>. This a 
              dialog to configure options in the constraint editor. It 
              is also available in the main <literal>
              Constraints</literal> tab and is discussed in detail 
              there (see <xref linkend="s1.ref.details_constraints"/>
              ).</para>

            </listitem>

          </itemizedlist>

          <para>To the right of the toolbar is a check box labeled 
          <literal>Syntax Assistant</literal> (unchecked by default), 
          which will enable the syntax assistant in the constraint 
          editor.</para>

          <para>If the syntax assistant is enabled, six drop down menus 
          are provided in a row immediately below the toolbar. These 
          provide standard templates for OCL that, when selected, will 
          be inserted into the constraint being edited.</para>

          <para>The syntax assistant can be made floating in a separate 
          window by button&nbsp;1 motion on the small divider area to the 
          left of the row of drop-down menus.</para>

          <itemizedlist>

            <listitem>

              <para><literal>General</literal>. General OCL 
              constructors. Entries: <literal>inv</literal> (inserts an 
              invariant); <literal>pre</literal> (inserts a 
              pre-condition); <literal>post</literal> (inserts a 
              post-condition); <literal>self</literal> (inserts a 
              self-reference); <literal>@pre</literal> (inserts a 
              reference to a value at the start of an operation); and 
              <literal>result</literal> (inserts a reference to a 
              previous result).</para>

            </listitem>

            <listitem>

              <para><literal>Basic Operators</literal>. Relational 
              operators and parentheses. Entries: <literal>=</literal>; 
              <literal>&lt;&gt;</literal>; <literal>&lt;</literal>; 
              <literal>&gt;</literal>; <literal>&lt;=</literal>; 
              <literal>&gt;=</literal>; and <literal>
              ()</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>Numbers</literal>. Arithmetic operators 
              and functions. Entries: <literal>+</literal>; <literal>
              -</literal>; <literal>*</literal>; <literal>/</literal>; 
              <literal>mod</literal>; <literal>div</literal>; <literal>
              abs</literal>; <literal>max</literal>; <literal>
              min</literal>; <literal>round</literal>; and <literal>
              floor</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>Strings</literal>. String functions. 
              Entries: <literal>concat</literal>; <literal>
              size</literal>; <literal>toLower</literal>; <literal>
              toUpper</literal>; and <literal>
              substring</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>Booleans</literal>. Logical functions. 
              Entries: <literal>or</literal>; <literal>and</literal>; 
              <literal>xor</literal>; <literal>not</literal>; <literal>
              implies</literal>; and <literal>
              if then else</literal>.</para>

            </listitem>

            <listitem>

              <para><literal>Collections</literal>. Operators and 
              functions on collections&mdash;bags, sets and sequences. The 
              large number of functions are organized into 
              sub-groups.</para>

              <itemizedlist>

                <listitem>

                  <para><literal>General</literal>. Functions that 
                  apply to all types of collection. Entries: <literal>
                  Collection {}</literal> (insert a new collection); 
                  <literal>Set {}</literal> (insert a a new set); 
                  <literal>Bag {}</literal> (insert a new bag); 
                  <literal>Sequence {}</literal> (insert a new 
                  sequence); <literal>size</literal>; <literal>
                  count</literal>; <literal>isEmpty</literal>; <literal>
                  notEmpty</literal>; <literal>includes</literal>; 
                  <literal>includesAll</literal>; <literal>
                  iterate</literal>; <literal>exists</literal>; 
                  <literal>forAll</literal>; <literal>
                  collect</literal>; <literal>select</literal>; 
                  <literal>reject</literal>; <literal>union</literal>; 
                  <literal>intersection</literal>; <literal>
                  including</literal>; <literal>excluding</literal>; 
                  and <literal>sum</literal>.</para>

                </listitem>

                <listitem>

                  <para><literal>Sets</literal>. Operators and 
                  functions that apply only to sets. Entries: <literal>
                  -</literal> (set difference); and <literal>
                  symmetricDifference</literal>.</para>

                </listitem>

                <listitem>

                  <para><literal>Sequences</literal>. Functions that 
                  apply to sequences. Entries: <literal>
                  first</literal>; <literal>last</literal>; <literal>
                  at</literal>; <literal>append</literal>; <literal>
                  prepend</literal>; and <literal>
                  subSequence</literal>.</para>

                </listitem>

              </itemizedlist>

            </listitem>

          </itemizedlist>

          <para>The remainder of the tab comprises a writable text area 
          containing the text to be edited. The mouse buttons have 
          their standard behavior within an editable text area (see 
          <xref linkend="s1.ref.mouse"/>).</para>

          <para>In addition, cut, copy and paste operations may be 
          invoked through the keyboard shortcuts <literal>
          Ctrl-X</literal>, <literal>Ctrl-C</literal> and <literal>
          Ctrl-V</literal> respectively.</para>

          <!--warning>

            <para>There is a known problem with the V0.20 release of 
            ArgoUML. The <literal>Cut</literal>, <literal>
            Copy</literal> and <literal>Paste</literal> functions on 
            the <literal>Edit</literal> menu cannot be used within the 
            constraint editor. If used they will work on the currently 
            selected model element in the editing pane.</para>

          </warning-->

        </sect2>

      </sect1>
      
      <sect1>
      <title>Stereotype Tab</title>
      
      <para>This tab shows the available and applied stereotypes for the 
      currently selected modelelement. 
      It consists of 2 panels and 2 buttons.
      The buttons allow to move the stereotypes
      from one list to the other.
      </para>
      
      <figure float="1" id="fig.ref.detpane_stereotype">

          <title>An example of a stereotype tab for a class.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/detpane_stereotype.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>
        
        <para>In the lists, between <literal>[]</literal> 
        the baseclass of the stereotypes is shown.
        E.g. in the figure above, 
        the <literal>thread [Classifier]</literal> stereotype 
        may be applied to all types of classifiers, 
        such as Class, UseCase,...
        </para>
        
      </sect1>

      <sect1>

        <title>Tagged Values Tab</title>

        <para>Tagged values are another extension mechanism provided by 
        UML. The user can define name-value pairs to be associated with 
        model elements which define properties of that model element. The names 
        are known as <emphasis>tags</emphasis>. UML pre-defines a 
        number of tags that are useful for many of its model elements.</para>

        <note>

          <para>The tag <literal>documentation</literal> is defined for 
          the top UML metaclass, <literal>Element</literal> and is so 
          available to all model elements. In ArgoUML documentation values 
          are provided through the <literal>Documentation</literal> 
          tab, rather than by using the <literal>
          Tagged Values</literal> tab.</para>

        </note>

        <para>The <literal>Tagged Values</literal> tab in ArgoUML 
        comprises a two column table, with a combo-box on 
        the left to select the tagdefinition
        and an editable box on the right for 
        the associated value. There is always at least one empty row 
        available for any new tag. 
        </para>
        
        <para>The button at the top of this tab allows creation of a new 
        tagdefinition. 
        After clicking this button, go to the properties tab first
        to set the name of the new tagdefinition. 
        <!-- Why does ArgoUML not do this? TODO: Create issue. -->
        </para>

        <para>The mouse buttons have their 
        standard behavior within the editable value area (see 
        <xref linkend="s1.ref.mouse"/>).
        In addition, 
        when in the value field,
        cut, copy and paste operations may be 
        invoked through the keyboard shortcuts <literal>
        Ctrl-X</literal>, <literal>Ctrl-C</literal> and <literal>
        Ctrl-V</literal> respectively.</para>

      </sect1>

      <sect1>

        <title>Checklist Tab</title>

        <para>Conducting design reviews and inspections is one of the 
        most effective ways of detecting errors during software 
        development. A design review typically consists of a small 
        number of designers, implementers, or other project 
        stakeholders holding a meeting to review a software development 
        artifact. Many development organizations have developed 
        checklists of common design problems for use in design review 
        meetings. Recent research indicated that reviewers inspecting 
        code without meeting, makeing use of these checklists, are just 
        as effective as design review meetings.</para>

        <para>Hence, a checklist feature has been added to ArgoUML, 
        that is much in the spirit of design review checklists. 
        However, ArgoUML&apos;s checklists are integrated into the 
        design tool user interface and the design task.</para>

        <para>A software designer using ArgoUML can see a review 
        checklist for any design element. The <quote>Checklist</quote> 
        tab presents a list of check-off items that is appropriate to 
        the currently selected design element. For example, when a 
        class is selected in a design diagram, the checklist tab shows 
        items that prompt critical thinking about classes. See the 
        figure below. Designers may check off items as they consider 
        them. Checked items are kept in the list to show what has 
        already been considered, while unchecked items prompt the 
        designer to consider new design issues. ArgoUML supplies many 
        different checklists with many possible items.</para>

        <figure float="1" id="fig.ref.detpane_checklist">

          <title>An example of a checklist for a class.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/detpane_checklist.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <caution>

          <para>In the V0.22 release of ArgoUML, this tab is not 
          completely implemented. E.g. the checks are not saved.</para>

        </caution>

      </sect1>

    </chapter>

    <chapter id="ch.ref.todopane">

      <title>The To-Do Pane</title>

      <sect1>

        <title>Introduction</title>

        <para><xref linkend="fig.ref.todo_pane"/> shows the ArgoUML 
        window with the to-do pane highlighted.</para>

        <figure float="1" id="fig.ref.todo_pane">

          <title>Overview of the to-do pane</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/todo_pane.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para>This pane provides access to the advice that comes from 
        the critics processes running within ArgoUML.</para>

        <para>A selector box at the top allows a choice of how the data 
        is presented, a button allows the display of the hierarchy to 
        be changed, and there is an indicator of the number of to-do 
        items identified.</para>

        <para>More information on critics can be found in the 
        discussion of the <literal>Critique</literal> menu (see 
        <xref linkend="s1.ref.menu_critique"/>).</para>

      </sect1>

      <sect1 id="s1.ref.todo_mouse">

        <title>Mouse Behavior in the To-Do Pane</title>

        <para>Behavior of the mouse in general, and the naming of the 
        buttons is covered in the chapter on the overall user interface 
        (see <xref linkend="ch.ref.ui"/>).</para>

        <sect2>

          <title>Button&nbsp;1 Click</title>

          <para>This action is generally used to select an item for 
          subsequent operations.</para>

          <para>Within the hierarchical display, elements which have 
          sub-hierarchies may be indicated by <guiicon>
          <inlinemediaobject><imageobject><imagedata align="center"
           fileref="images/icons/hierarchy_closed.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          when the hierarchy is hidden and <guiicon>
          <inlinemediaobject><imageobject><imagedata align="center"
           fileref="images/icons/hierarchy_open.gif"
           format="GIF"/></imageobject></inlinemediaobject></guiicon> 
          when the hierarchy is open.</para>

          <para>When these icons are displayed, the display of the 
          hierarchy is toggled by button&nbsp;1 click on these icons.</para>

          <para>Button&nbsp;1 click over the headline of any to-do item will 
          cause its details to be shown in the <literal>
          To Do Item</literal> tab of the details pane. That tab is 
          automatically selected if it is not currently visible.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;1 Double Click</title>

          <para>When applied to the folder icon alongside a hierarchy 
          category, this will cause the display of that hierarchy to be 
          toggled.</para>

          <para>When applied to a headline, button&nbsp;1 double click will 
          show the diagram for the model element to which the to-do item 
          applies in the editing pane and select the model element on the 
          diagram using an appropriate clarifier (the model element may be 
          highlighted, underlined with a wavy line or surrounded by a 
          colored box as appropriate).</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Actions</title>

          <para>There are no button&nbsp;2 functions in the to-do 
          pane.</para>

        </sect2>

        <sect2>

          <title>Button&nbsp;2 Double Click</title>

          <para>There are no button&nbsp;2 functions in the to-do 
          pane.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Presentation Selection</title>

        <para>At the top of the pane is a drop-down selector 
        controlling how the to-do items are presented. The to-do items 
        may be presented in six different ways. This setting is not 
        stored persistently, i.e. it is on its default vallue when 
        ArgoUML is started.</para>

        <itemizedlist>

          <listitem>

            <para><literal>By Priority</literal>. This is the default 
            setting. The to-do items are organized into three 
            hierarchies by priority: <literal>High</literal>, <literal>
            Medium</literal> and <literal>Low</literal>. The priority 
            associated with the to-do items generated by a particular 
            critic may be altered through the <literal>
            Critique &gt; Browse Critics...</literal> menu (see 
            <xref linkend="s2.ref.menu_browse_critics"/>).</para>

          </listitem>

          <listitem>

            <para><literal>By Decision</literal>. The to-do items are 
            organized into 17 hierarchies by design issue: <literal>
            Uncategorized</literal>, <literal>
            Class Selection</literal>, <literal>Behavior</literal>, 
            <literal>Naming</literal>, <literal>Storage</literal>, 
            <literal>Inheritance</literal>, <literal>
            Containment</literal>, <literal>
            Planned Extensions</literal>, <literal>
            State Machines</literal>, <literal>
            Design Patterns</literal>, <literal>
            Relationships</literal>, <literal>Instantiation</literal>, 
            <literal>Modularity</literal>, <literal>
            Expected Usage</literal>, <literal>Methods</literal>, 
            <literal>Code Generation</literal> and <literal>
            Stereotypes</literal>. The details of the critics in each 
            category are discussed in 
            <xref linkend="s2.ref.menu_design_issues"/>.</para>

          </listitem>

          <listitem>

            <para><literal>By Goal</literal>. ArgoUML has a concept 
            that critics may be grouped according to the user goals 
            they affect. This presentation groups the to-do items into 
            hierarchies by goal.</para>

            <caution>

              <para>In the current release of ArgoUML there is only one 
              goal, <literal>Unspecified</literal> and all to-do items 
              will appear under this heading.</para>

            </caution>

          </listitem>

          <listitem>

            <para><literal>By Offender</literal>. The to-do items are 
            organized into a hierarchy according to the model element that 
            caused the problem. Todo items that were manually created 
            with the &quot;New ToDo item&quot; button (i.e. not by a 
            critic), are not listed here.</para>

          </listitem>

          <listitem>

            <para><literal>By Poster</literal>. The to-do items are 
            organized into a hierarchy according to which critic 
            generated the to-do item. The class name of the critic is 
            listed instead of just its headline name since the former 
            is guaranteed to be a unique name.</para>

          </listitem>

          <listitem>

            <para><literal>By Knowledge Type</literal>. ArgoUML has the 
            concept that a critic reflects a deficiency in a category 
            of knowledge. This presentation option groups the critics 
            according to their knowledge category: <literal>
            Designer&apos;s</literal>, <literal>Correctness</literal>, 
            <literal>Completeness</literal>, <literal>
            Consistency</literal>, <literal>Syntax</literal>, <literal>
            Semantics</literal>, <literal>Optimization</literal>, 
            <literal>Presentational</literal>, <literal>
            Organizational</literal>, <literal>Experiencial</literal> 
            and <literal>Tool</literal>. The former category 
            (Designer&apos;s) contains the manually entered todo 
            items.</para>

          </listitem>

        </itemizedlist>

      </sect1>

      <sect1>

        <title>Item Count</title>

        <para>To the right of the flat/hierarchical button is a count 
        of the number of to-do items currently found. It will be 
        highlighted in yellow when the number of to-do items grows 
        above 50 todo items, and red when above 100.</para>

      </sect1>

    </chapter>

    <chapter id="ch.ref.critics">

      <title>The Critics</title>

      <sect1>

        <title>Introduction</title>

        <para>The key feature that distinguishes ArgoUML from other UML 
        CASE tools is its use of concepts from cognitive psychology. 
        The theory behind this is well described in Jason Robbins&apos; 
        PhD dissertation 
        <ulink url="http://argouml.tigris.org/docs/robbins_dissertation/">
        http://argouml.tigris.org/docs/robbins_dissertation/</ulink>.</para>

        <para>Critics are one of the main ways in which these ideas are 
        implemented. Running in the background they offer advice to the 
        designer which may be accepted or ignored. A key point is that 
        they do not <emphasis>impose</emphasis> a decision on the 
        designer.</para>

        <note>

          <para>The critics are asynchronous processes that run in 
          parallel with the main ArgoUML tool. Changes typically take a 
          second or two to propagate as the critics wake up.</para>

        </note>

        <sect2>

          <title>Terminology</title>

          <para>The <emphasis>critics</emphasis> are background 
          processes, which evaluate the current model according to 
          various <quote>good</quote> design criteria. There is one 
          critic for every design criterion.</para>

          <para>The output of a critic is a 
          <emphasis>critique</emphasis>&mdash;a statement about some aspect 
          of the model that does not appear to follow good design 
          practice.</para>

          <para>Finally a critique will generally suggest how the bad 
          design issue it has identified can be rectified, by raising a 
          <emphasis>to-do item</emphasis>.</para>

        </sect2>

        <sect2>

          <title>Design Issues</title>

          <para>ArgoUML categorizes critics according the the design 
          issue they address (some critics may be in more than one 
          category). At present there are 16 such categories.</para>

          <para>Within this manual the descriptions of critics are 
          grouped in sections by design issue.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_uncategorized">

        <title>Uncategorized</title>

        <para>These are critics that do not fit into any other 
        category.</para>

        <para>ArgoUML has no critics in this category. Maybe some will 
        be added in later versions.</para>

      </sect1>

      <sect1 id="s1.ref.design_issues_class_selection">

        <title>Class Selection</title>

        <para>These are critics concerning how classes are chosen and 
        used.</para>

        <para>ArgoUML has the following critics in this category.</para>

        <sect2 id="critics.CrNonAggDataType">

          <title>Wrap DataType</title>

          <para>DataTypes are not full classes within UML 1.4. They can 
          only have enumeration literals as values, and only support 
          <literal>query</literal> operations (that is operations that 
          do not change the DataType&apos;s state).</para>

          <para>DataTypes cannot be associated with classes, unless the 
          DataType is part of a composite (black diamond) aggregation. 
          Such an association relects the tight binding of a collection 
          of DataType instances to a class instance. In effect such a 
          DataType is an attribute of the class with 
          multiplicity.</para>

          <para>Good OOA&amp;D depends on careful choices about which 
          entities to represent as full objects and which to represent 
          as attributes of objects.</para>

          <para>There are two options to fix this problem.</para>

          <itemizedlist>

            <listitem>

              <para>Replace the DataType with a full class.</para>

            </listitem>

            <listitem>

              <para>or change the association aggregation to composite 
              relationship at the DataType end.</para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="critics.CrTooManyClasses">

          <title>Reduce Classes in namespace &lt;namespace&gt;</title>

          <para>Suggestion to improve understandability by having fewer 
          classes in one namespace. If one namespace 
          (such as the model, a package, or a class) 
          has too many classes
          it may become very difficult for humans to 
          understand. Defining an understandable set of
          namespaces 
          is an important part of your design.</para>
          
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of classes
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more classes until the critic fires again.
            Restarting ArgoUML resets this number to its default: 20.
            </para>
          </caution>

        </sect2>

        <sect2 id="critics.CrNodesOverlap">

          <title>Clean Up Diagram</title>

          <para>Suggestion that the diagram could be improved by moving 
          model elements that are overlapping.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_naming">

        <title>Naming</title>

        <para>These are critics concerning the naming of model elements. The 
        current version of ArgoUML has 18 critics in this 
        category.</para>

        <sect2 id="critics.CrAssocNameConflict">

          <title>Resolve Association Name Conflict</title>

          <para>Suggestion that two association names in the same 
          namespace have the same name. This is not permitted in 
          UML.</para>

        </sect2>

        <sect2 id="critics.CrAttrNameConflict">

          <title>Revise Attribute Names to Avoid Conflict</title>

          <para>Suggestion that two attribute names of a class have the 
          same name. This is not permitted in UML.</para>

          <note>

            <para>The problem may be caused by inheritance of an 
            attribute through a generalization relationship.</para>

          </note>

        </sect2>

        <sect2 id="critics.CrOperNameConflict">

          <title>Change Names or Signatures in a model element</title>

          <para>Two operations in &lt;model element&gt; have the same 
          signature. This means their name is the same, and the list of 
          parameters has the same type.</para>

          <para>Where there are conflicting signatures, correct code 
          cannot be generated for mainstream OO languages. It also 
          leads to very unclear semantics of the design.</para>

          <para>In comparing signatures, this critic considers:</para>

          <orderedlist>

            <listitem>

              <para>the name;</para>

            </listitem>

            <listitem>

              <para>the list of in, out and in-out parameter types 
              <emphasis>in order</emphasis>; and</para>

            </listitem>

          </orderedlist>

          <para>Only if these all match in both type and order, will 
          the signatures be considered as the same.</para>

          <para>This follows the line of Java/C++ in ignoring the 
          return parameters for the signature. This 
          <emphasis>may</emphasis> be unsatisfactory for some 
          functional OO languages.</para>

          <note>

            <para>Some purists would argue that the comparison should 
            really differentiate between in, out and in-out parameters. 
            However no practical programming language can do this when 
            resolving an overloaded method invocation, so this critic 
            lumps them all together.</para>

          </note>

        </sect2>

        <sect2 id="critics.CrDupRoleNames">

          <title>Duplicate End (Role) Names for an Association</title>

          <para>The specified association has two (or more) ends 
          (roles) with the same name. One of the well-formedness rules 
          in UML 1.4 for associations, is that all end (role) names 
          must be unique.</para>

          <para>This ensures that there can be unambiguous reference to 
          the ends of the association.</para>

          <para>To fix this, manually select the association and change 
          the names of one or more of the offending ends (roles) using 
          the button&nbsp;2 pop-up menu or the property sheet.</para>

        </sect2>

        <sect2 id="critics.CrNameConflictAC">

          <title>Role name conflicts with member</title>

          <para>A suggestions that good design avoids role names for 
          associations that clash with attributes or operations of the 
          source class. Roles may be realized in the code as attributes 
          or operations, causing code generation problems.</para>

        </sect2>

        <sect2 id="critics.CrMissingClassName">

          <title>Choose a Name (Classes and Interfaces)</title>

          <para>The class or interface concerned has been given no name 
          (it will appear in the model as <literal>Unnamed</literal>). 
          Suggestion that good design requires that all interfaces and 
          classes are named.</para>

        </sect2>

        <sect2 id="critics.CrNameConflict">

          <title>Name conflict in a namespace</title>

          <para>The namespace (e.g. package) concerned 
          contains a class or interface specified that has 
          the same name as another (in the same namespace), 
          which is bad design and will prevent valid code generation.</para>

        </sect2>

        <sect2 id="critics.CrDisambigClassName">

          <title>Choose a Unique Name for a model element (Classes and 
          Interfaces)</title>

          <para>Suggestion that the class or interface specified has 
          the same name as another (in the namespace), which is bad 
          design and will prevent valid code generation.</para>

        </sect2>

        <sect2 id="critics.CrMissingAttrName">

          <title>Choose a Name (Attributes)</title>

          <para>The attribute concerned has been given no name (it will 
          appear in the model as <literal>(Unnamed Attribute)</literal>). 
          Suggestion that good design requires that all attributes are 
          named.</para>

        </sect2>

        <sect2 id="critics.CrMissingOperName">

          <title>Choose a Name (Operations)</title>

          <para>The operation concerned has been given no name (it will 
          appear in the model as <literal>(Unnamed Operation)</literal>). 
          Suggestion that good design requires that all operations are 
          named.</para>

        </sect2>

        <sect2 id="critics.CrMissingStateName">

          <title>Choose a Name (States)</title>

          <para>The state concerned has been given no name (it will 
          appear in the model as <literal>(Unnamed State)</literal>). 
          Suggestion that good design requires that all states are 
          named.</para>

        </sect2>

        <sect2 id="critics.CrDisambigStateName">

          <title>Choose a Unique Name for a (State related) 
          model element</title>

          <para>Suggestion that the state specified has the same name 
          as another (in the current statechart diagram), which is bad 
          design and will prevent valid code generation.</para>

        </sect2>

        <sect2 id="critics.CrNameConfusion">

          <title>Revise Name to Avoid Confusion</title>

          <para>Two names in the same namespace have very similar names 
          (differing only by one character). Suggestion this could 
          potentially lead to confusion.</para>

          <caution>

            <para>This critic can be particularly annoying, since at 
            times it is useful and good design to have a series of 
            model elements <literal>var1</literal>, <literal>var2</literal> 
            etc.</para>

            <para>It is important to remember that critics offer 
            guidance, and are not always correct. ArgoUML lets you 
            dismiss the resulting to-do items through the to-do pane 
            (see <xref linkend="ch.ref.todopane"/>).</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrIllegalName">

          <title>Choose a Legal Name</title>

          <para>All model element names in ArgoUML must use only letters, 
          digits and underscore characters. This critic suggests an 
          entity has not met this requirement.</para>

        </sect2>

        <sect2 id="critics.CrReservedName">

          <title>Change a model element to a Non-Reserved Word</title>

          <para>Suggestion that this model element&apos;s name is the same 
          as a reserved word in UML (or within one character of one), 
          which is not permitted.</para>

        </sect2>

        <sect2 id="critics.CrUnconventionalOperName">

          <title>Choose a Better Operation Name</title>

          <para>Suggestion that an operation has not followed the 
          naming convention that operation names begin with lower case 
          letters.</para>

          <caution>

            <para>Following the Java and C++ convention most designers 
            give their constructors the same name as the class, which 
            begins with an upper case character. In ArgoUML, this will 
            trigger this critic, unless the constructor is stereotyped 
            <literal>&laquo;create&raquo;</literal>.</para>

            <para>It is important to remember that critics offer 
            guidance, and are not always correct. ArgoUML lets you 
            dismiss the resulting to-do items through the to-do pane 
            (see <xref linkend="ch.ref.todopane"/>).</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrUnconventionalAttrName">

          <title>Choose a Better Attribute Name</title>

          <para>Suggestion that an attribute has not followed the 
          naming convention that attribute names begin with lower case 
          letters.</para>

        </sect2>

        <sect2 id="critics.CrUnconventionalClassName">

          <title>Capitalize Class Name</title>

          <para>Suggestion that a class has not followed the naming 
          convention that classes begin with upper case letters.</para>

          <note>

            <para>Although not triggering this critic, the same 
            convention should apply to interfaces.</para>

          </note>

        </sect2>

        <sect2 id="critics.CrUnconventionalPackName">

          <title>Revise Package Name</title>

          <para>Suggestion that a package has not followed the naming 
          convention of using lower case letters with periods used to 
          indicated sub-packages.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_storage">

        <title>Storage</title>

        <para>Critics concerning attributes of classes.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2>

          <title>Revise Attribute Names to Avoid Conflict</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrAttrNameConflict"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrNoInstanceVariables">

          <title>Add Instance Variables to a Class</title>

          <para>Suggestion that no instance variables have been 
          specified for the given class. Such classes may be created to 
          specify static attributes and methods, but by convention 
          should then be given the stereotype <literal>
          &laquo;utility&raquo;</literal>.</para>

        </sect2>

        <sect2 id="critics.CrConstructorNeeded">

          <title>Add a Constructor to a Class</title>

          <para>You have not yet defined a constructor for class 
          <emphasis>class</emphasis>. Constructors initialize new 
          instances such that their attributes have valid values. This 
          class probably needs a constructor because not all of its 
          attributes have initial values.</para>

          <para>Defining good constructors is key to establishing class 
          invariants, and class invariants are a powerful aid in 
          writing solid code.</para>

          <para>To fix this, add a constructor manually by clicking on 
          <emphasis>class</emphasis> in the explorer and adding an 
          operation using the context sensitive pop-up menu in the 
          property tab, or select <emphasis>class</emphasis> where it 
          appears on a class diagram and use the <literal>Add 
          Operation</literal> tool.</para>

          <para>In the UML 1.4 standard, a constructor is an operation 
          with the stereotype &laquo;create&raquo;. Although not strictly standard, 
          ArgoUML will also accept &laquo;Create&raquo; as a stereotype for 
          constructors.</para>

          <para>By convention in Java and C++ a constructor has the 
          same name as the class, is not static, and returns no value. 
          ArgoUML will also accept any operation that follows these 
          conventions as a constructor even if it is not stereotyped 
          &laquo;create&raquo;.</para>

          <caution>

            <para>Operators are created in ArgoUML with a default 
            return parameter (named <literal>return</literal>). You 
            will need to remove this parameter to meet the Java/C++ 
            convention.</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrTooManyAttr">

          <title>Reduce Attributes on a Class</title>

          <para>Suggestion that the class has too many attributes for a 
          good design, and is at risk of becoming a design 
          bottleneck.</para>
          
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of attributes 
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more attributes until the critic fires again.
            Restarting ArgoUML resets this number to its default: 7.
            </para>
          </caution>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_planned_extensions">

        <title>Planned Extensions</title>

        <para>Critics concerning interfaces and subclasses.</para>

        <note>

          <para>It is not clear why this category has the name 
          <quote>Planned Extensions</quote>.</para>

        </note>

        <para>The current version of ArgoUML has three critics in this 
        category.</para>

        <sect2 id="critics.CrIntefaceAllPublic">

          <title>Operations in Interfaces must be public</title>

          <para>Suggestion that there is no point in having non-public 
          operations in Interfaces, since they must be visible to be 
          realized by a class.</para>

        </sect2>

        <sect2 id="critics.CrInterfaceOperOnly">

          <title>Interfaces may only have operations</title>

          <para>Suggestion that an interfaces has attributes defined. 
          The UML standard defines interfaces to have operations.</para>

          <caution>

            <para>ArgoUML does not allow you to add attributes to 
            interfaces, so this should never occur in the ArgoUML 
            model. It might trigger if a project has been loaded with 
            XMI created by another tool.</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrSubclassReference">

          <title>Remove Reference to Specific Subclass</title>

          <para>Suggestion that in a good design, a class should not 
          reference its subclasses directly through attributes, 
          operations or associations.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_state_machines">

        <title>State Machines</title>

        <para>Critics concerning state machines.</para>

        <para>ArgoUML has the following critics in this category.</para>

        <sect2 id="critics.CrTooManyTransitions">

          <title>Reduce Transitions on &lt;state&gt;</title>

          <para>Suggestion given state is involved in so many 
          transitions it may be a maintenance bottleneck.</para>
                    
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of transitions 
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more transition until the critic fires again.
            Restarting ArgoUML resets this number to its default: 10.
            </para>
          </caution>
          

        </sect2>

        <sect2 id="critics.CrTooManyStates">

          <title>Reduce States in machine &lt;machine&gt;</title>

          <para>Suggestion that the given state machine has so many 
          states as to be confusing and should be simplified (perhaps 
          by breaking into several machines, or using a 
          hierarchy).</para>
                    
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of states 
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more states until the critic fires again.
            Restarting ArgoUML resets this number to its default: 20.
            </para>
          </caution>
          

        </sect2>

        <sect2 id="critics.CrNoTransitions">

          <title>Add Transitions to &lt;state&gt;</title>

          <para>Suggestion that the given state requires both incoming 
          and outgoing transitions.</para>

        </sect2>

        <sect2 id="critics.CrNoIncomingTransitions">

          <title>Add Incoming Transitions to &lt;model element&gt;</title>

          <para>Suggestion that the given state requires incoming 
          transitions.</para>

        </sect2>

        <sect2 id="critics.CrNoOutgoingTransitions">

          <title>Add Outgoing Transitions from &lt;model element&gt;</title>

          <para>Suggestion that the given state requires outgoing 
          transitions.</para>

        </sect2>

        <sect2 id="critics.CrMultipleInitialStates">

          <title>Remove Extra Initial States</title>

          <para>Suggestion that there is more than one initial state in 
          the state machine or composite state, which is not permitted 
          in UML.</para>

        </sect2>

        <sect2 id="critics.CrNoInitialState">

          <title>Place an Initial State</title>

          <para>Suggestion that there is no initial state in the state 
          machine or composite state.</para>

        </sect2>

        <sect2 id="critics.CrNoTriggerOrGuard">

          <title>Add Trigger or Guard to Transition</title>

          <para>Suggestion that a transition is missing either a 
          trigger or guard, one at least of which is required for it to 
          be taken.</para>

        </sect2>

        <sect2 id="critics.CrInvalidJoin">

          <title>Change Join Transitions</title>

          <para>Suggestion that the join pseudostate has an invalid 
          number of transitions. Normally there should be one outgoing 
          and two or more incoming.</para>

        </sect2>

        <sect2 id="critics.CrInvalidFork">

          <title>Change Fork Transitions</title>

          <para>Suggestion that the fork pseudostate has an invalid 
          number of transitions. Normally there should be one incoming 
          and two or more outgoing.</para>

        </sect2>

        <sect2 id="critics.CrInvalidBranch">

          <title>Add Choice/Junction Transitions</title>

          <para>Suggestion that the branch (choice or junction) 
          pseudostate has an invalid number of transitions. Normally 
          there should be at least one incoming transition and at least 
          one outgoing transition.</para>

        </sect2>

        <sect2 id="critics.CrNoGuard">

          <title>Add Guard to Transition</title>

          <para>Suggestion that the transition requires a guard.</para>

          <caution>

            <para>It is not clear that this is a valid critic. It is 
            perfectly acceptable to have a transition without a 
            guard&mdash;the transition is always taken when the trigger is 
            invoked.</para>

          </caution>

        </sect2>

        <sect2>

          <title>Clean Up Diagram</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrNodesOverlap"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrZeroLengthEdge">

          <title>Make Edge More Visible</title>

          <para>Suggestion that an edge model element such as an association 
          or abstraction is so short it may be missed. Move the 
          connected model elements apart to make the edge more 
          visible.</para>

        </sect2>

        <sect2 id="critics.CrMultiComposite">

          <title>Composite Association End with Multiplicity &gt; 
          1</title>

          <para>An instance may not belong by composition to more than 
          one composite instance. You must change the multiplicity at 
          the composite end of the association to either 0..1 or 1..1 
          (1) for your model to make sense.</para>

          <para>Remember that composition is the stronger aggregation 
          kind and aggregation is the weaker. The problem can be 
          compared to a model where a finger can be an integral part of 
          several hands at the same time.</para>

          <para>This is the second well-formedness rule on 
          AssociationEnd in UML 1.4.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_design_patterns">

        <title>Design Patterns</title>

        <para>Critics concerning design pattern usage in ArgoUML.</para>

        <para>These relate to the use of patterns as described by the 
        so called <quote>Gang of Four</quote>. ArgoUML also uses this 
        category for critics associated with deployment and sequence 
        diagrams. The current version of ArgoUML has the following 
        critics in this category.</para>

        <sect2 id="critics.CrConsiderSingleton">

          <title>Consider using Singleton Pattern for 
          &lt;class&gt;</title>

          <para>The <emphasis>class</emphasis> has no non-static 
          attributes nor any associations that are navigable away from 
          instances of this class. This means that every instance of 
          this class will be identical to every other instance, since 
          there will be nothing about the instances that can 
          differentiate them.</para>

          <para>Under these circumstances you should consider making 
          explicit that you have exactly one instance of this class, by 
          using the singleton Pattern. Using the singleton pattern can 
          save time and memory space. Within ArgoUML this can be done 
          by using the &laquo;singleton&raquo; stereotype on this class.</para>

          <para>If it is not your intent to have a single instance, you 
          should define instance variables (i.e. non-static attributes) 
          and/or outgoing associations that will represent differences 
          bewteen instances.</para>

          <para>Having specified <emphasis>class</emphasis> as a 
          singleton, you need to define the class so there can only be 
          a single instance. This will complete the information 
          representation part of your design. To achieve this you need 
          to do the following.</para>

          <orderedlist>

            <listitem>

              <para>You must define a static attribute (a class 
              variable) holding the instance. This must therefore have 
              <emphasis>class</emphasis> as its type.</para>

            </listitem>

            <listitem>

              <para>You must have only private constructors so that new 
              instances cannot be made by other code. The creation of 
              the single instance could be through a suitable helper 
              operation, which invokes this private constructor just 
              once.</para>

            </listitem>

            <listitem>

              <para>You must have at least one constructor to override 
              the default constructor, so that the default constructor 
              is not used to create multiple instances.</para>

            </listitem>

          </orderedlist>

          <para>For the definition of a constructor under the UML 1.4 
          standard, and extensions to that definition accepted by 
          ArgoUML see <xref linkend="critics.CrConstructorNeeded"/>
          .</para>

        </sect2>

        <sect2 id="critics.CrSingletonViolated">

          <title>Singleton Stereotype Violated in &lt;class&gt;</title>

          <para>This class is marked with the &laquo;singleton&raquo; stereotype, 
          but it does not satisfy the constraints imposed on singletons 
          (ArgoUML will also accept &laquo;Singleton&raquo; stereotype as defining 
          a singleton). A singleton class can have at most one 
          instance. This means that the class must meet the design 
          criteria for a singleton (see 
          <xref linkend="critics.CrConsiderSingleton"/>).</para>

          <para>Whenever you mark a class with a stereotype, the class 
          should satisfy all constraints of the stereotype. This is an 
          important part of making a self-consistent and understangle 
          design. Using the singleton pattern can save time and memory 
          space.</para>

          <para>If you no longer want this class to be a singleton, 
          remove the &laquo;singleton&raquo; stereotype by clicking on the class 
          and selecting the blank selection on the stereotype drop-down 
          within the properties tab.</para>

          <para>To apply the singleton pattern you should follow the 
          directions in <xref linkend="critics.CrConsiderSingleton"/>
          .</para>

        </sect2>

        <sect2 id="critics.CrNodeInsideElement">

          <title>Nodes normally have no enclosers</title>

          <para>A suggestion that nodes should not be drawn inside 
          other model elements on the deployment diagram, since they 
          represent an autonomous physical object.</para>

        </sect2>

        <sect2 id="critics.CrNodeInstanceInsideElement">

          <title>NodeInstances normally have no enclosers</title>

          <para>A suggestion that node instances should not be drawn 
          inside other model elements on the deployment diagram, since they 
          represent an autonomous physical object.</para>

        </sect2>

        <sect2 id="critics.CrComponentWithoutNode">

          <title>Components normally are inside nodes</title>

          <para>A suggestion that components represent the logical 
          entities within physical nodes, and so should be drawn within 
          a node, where nodes are shown on the deployment 
          diagram.</para>

        </sect2>

        <sect2 id="critics.CrCompInstanceWithoutNode">

          <title>ComponentInstances normally are inside nodes</title>

          <para>A suggestion that component instances represent the 
          logical entities within physical nodes, and so should be 
          drawn within a node instance, where node instances are shown 
          on the deployment diagram.</para>

        </sect2>

        <sect2 id="critics.CrClassWithoutComponent">

          <title>Classes normally are inside components</title>

          <para>A suggestion that classes, as model elements making up 
          components, should be drawn within components on the 
          deployment diagram.</para>

        </sect2>

        <sect2 id="critics.CrInterfaceWithoutComponent">

          <title>Interfaces normally are inside components</title>

          <para>A suggestion that interfaces, as model elements making up 
          components, should be drawn within components on the 
          deployment diagram.</para>

        </sect2>

        <sect2 id="critics.CrObjectWithoutComponent">

          <title>Objects normally are inside components</title>

          <para>A suggestion that objects, as instances of model elements 
          making up components, should be drawn within components or 
          component instances on the deployment diagram.</para>

        </sect2>

        <sect2 id="critics.CrWrongLinkEnds">

          <title>LinkEnds have not the same locations</title>

          <para>A suggestion that a link (e.g. association) connecting 
          objects on a deployment diagram has one end in a component 
          and the other in a component instance (since objects can be 
          in either). This makes no sense.</para>

        </sect2>

        <sect2 id="critics.CrInstanceWithoutClassifier">

          <title>Set classifier (Deployment Diagram)</title>

          <para>Suggestion that there is an instance (object) without 
          an associated classifier (class, datatype) on a deployment 
          diagram.</para>

        </sect2>

        <sect2 id="critics.CrCallWithoutReturn">

          <title>Missing return-actions</title>

          <para>Suggestion that a sequence diagram has a send or call 
          action without a corresponding return action.</para>

        </sect2>

        <sect2 id="critics.CrReturnWithoutCall">

          <title>Missing call(send)-action</title>

          <para>Suggestion that a sequence diagram has a return action, 
          but no preceding call or send action.</para>

        </sect2>

        <sect2 id="critics.CrLinkWithoutStimulus">

          <title>No Stimuli on these links</title>

          <para>Suggestion that a sequence diagram has a link 
          connecting objects without an associated stimulus (without 
          which the link is meaningless).</para>

          <warning>

            <para>Triggering this critic indicates a serious problem, 
            since ArgoUML provides no mechanism for creating a link 
            without a stimulus. It probably indicates that the diagram 
            was created by loading a corrupt project, with an XMI file 
            describing a link without a stimulus, possibly created by a 
            tool other than ArgoUML.</para>

          </warning>

        </sect2>

        <sect2 id="critics.CrSeqInstanceWithoutClassifier">

          <title>Set Classifier (Sequence Diagram)</title>

          <para>Suggestion that there is an object without an 
          associated classifier (class, datatype) on a sequence 
          diagram.</para>

        </sect2>

        <sect2 id="critics.CrStimulusWithWrongPosition">

          <title>Wrong position of these stimuli</title>

          <para>Suggestion that the initiation of send/call-return 
          message exchanges in a sequence diagram does not properly 
          initiate from left to right.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_relationships">

        <title>Relationships</title>

        <para>Critics concerning associations in ArgoUML.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2 id="critics.CrCircularAssocClass">

          <title>Circular Association</title>

          <para>Suggestion that an association class has a role that 
          refers back directly to itself, which is not permitted.</para>

          <warning>

            <para>This critic is meaningless in the V0.14 version of 
            ArgoUML which does not support association classes.</para>

          </warning>

        </sect2>

        <sect2 id="critics.CrUnnavigableAssoc">

          <title>Make &lt;association&gt; Navigable</title>

          <para>Suggestion that the association referred to is not 
          navigable in either direction. This is permitted in the UML 
          standard, but has no obvious meaning in any practical 
          design.</para>

        </sect2>

        <sect2 id="critics.CrNavFromInterface">

          <title>Remove Navigation from Interface via 
          &lt;association&gt;</title>

          <para>Associations involving an interface can be not be 
          navigable in the direction from the interface. This is 
          because interfaces contain only operation declarations and 
          cannot hold pointers to other objects.</para>

          <para>This part of the design should be changed before you 
          can generate code from this design. If you do generate code 
          before fixing this problem, the code will not match the 
          design.</para>

          <para>To fix this, select the association and use the 
          <literal>Properties</literal> tab to select in turn each 
          association end that is <emphasis>not</emphasis> connected to 
          the interface. Uncheck <literal>Navigable</literal> for each 
          of these ends.</para>

          <para>The association should then appear with a stick 
          arrowhead pointed towards the interface</para>

          <para>When an association between a class and interface is 
          created in ArgoUML, it is by default navigable only from the 
          class to the interface. However, ArgoUML does not prevent to 
          change the navigability afterwards into a wrong situation. 
          Which will cause this critic to be triggered.</para>

        </sect2>

        <sect2 id="critics.CrNoAssociations">

          <title>Add Associations to &lt;model element&gt;</title>

          <para>Suggestion that the specified model element (actor, use case 
          or class) has no associations connecting it to other 
          model elements. This is required for the model element to be useful in 
          a design.</para>

        </sect2>

        <sect2>

          <title>Remove Reference to Specific Subclass</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrSubclassReference"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrTooManyAssoc">

          <title>Reduce Associations on &lt;model element&gt;</title>

          <para>Suggestion that the given model element (actor, use case, 
          class or interface) has so many associations it may be a 
          maintenance bottleneck.</para>
          
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of associations 
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more associations until the critic fires again.
            Restarting ArgoUML resets this number to its default: 7.
            </para>
          </caution>

        </sect2>

        <sect2>

          <title>Make Edge More Visible</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrZeroLengthEdge"/>
          ).</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_instantiation">

        <title>Instantiation</title>

        <para>Critics concerning instantiation of classifiers in 
        ArgoUML.</para>

        <para>The current version of ArgoUML has no critics in this 
        category.</para>

      </sect1>

      <sect1 id="s1.ref.design_issues_modularity">

        <title>Modularity</title>

        <para>Critics concerning modular development in ArgoUML.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2 id="critics.CrCrossNamespaceAssoc">

          <title>Classifier not in Namespace of its Association</title>

          <para>One of the well-formedness rules in UML 1.4 for 
          associations, is that all the classifiers attached to the 
          ends of the association should belong to the same namespace 
          as the association.</para>

          <para>If this were not the case, there would be no naming, by 
          which each end could refer to all the others.</para>

          <para>This critic is triggered when an association does not 
          meet this criterion. The solution is to delete the 
          association, and recreate it on a diagram, whose namespace 
          includes those of all the attached classifiers.</para>

          <caution>

            <para>In the current implementation of ArgoUML this critic 
            does not handle hierarchical namespaces. As a consequence 
            it will trigger for associations where the immediate 
            namespaces of the attached classifiers is different, even 
            though they are part of the same namespace hierarchy.</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrEmptyPackage">

          <title>Add Elements to Package &lt;package&gt;</title>

          <para>Suggestion that the specified package has no content. 
          Good design suggests packages are created to put things 
          in.</para>

          <note>

            <para>This will always trigger when you first create a 
            package, since you cannot create one that is not 
            empty!</para>

          </note>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_expected_usage">

        <title>Expected Usage</title>

        <para>Critics concerning generally accepted good practice in 
        ArgoUML.</para>

        <para>The current version of ArgoUML has one critic in this 
        category.</para>

        <sect2>

          <title>Clean Up Diagram</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrNodesOverlap"/>
          ).</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_methods">

        <title>Methods</title>

        <para>Critics concerning operations in ArgoUML.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2>

          <title>Change Names or Signatures in &lt;model element&gt;</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrOperNameConflict"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrClassMustBeAbstract">

          <title>Class Must be Abstract</title>

          <para>Suggestion that a class that inherits or defines 
          abstract operations must be marked abstract.</para>

        </sect2>

        <sect2 id="critics.CrNoOperations">

          <title>Add Operations to &lt;class&gt;</title>

          <para>Suggestion that the specified class has no operations 
          defined. This is required for the class to be useful in a 
          design.</para>

        </sect2>

        <sect2 id="critics.CrTooManyOper">

          <title>Reduce Operations on &lt;model element&gt;</title>

          <para>Suggestion that the model element (class or interface) has 
          too many operations for a good design, and is at risk of 
          becoming a design bottleneck.</para>
          
          <para>The Wizard of this critic allows setting of the treshold, 
          i.e. the maximum number of operations 
          allowed before this critic fires.  </para>

          <caution>
            <para>This number is not stored persistently, and
            there is no way to reduce it after it has been set higher,
            except by creating more operations until the critic fires again.
            Restarting ArgoUML resets this number to its default: 20.
            </para>
          </caution>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_code_generation">

        <title>Code Generation</title>

        <para>Critics concerning code generation in ArgoUML.</para>

        <para>The current version of ArgoUML has one critic in this 
        category.</para>

        <sect2 id="critics.CrMultipleInheritance">

          <title>Change Multiple Inheritance to interfaces</title>

          <para>Suggestion that a class has multiple generalizations, 
          which is permitted by UML, but cannot be generated into Java 
          code, because Java does not support multiple 
          inheritance.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_stereotypes">

        <title>Stereotypes</title>

        <para>Critics concerning stereotypes in ArgoUML.</para>

        <para>The current version of ArgoUML has no critics in this 
        category.</para>

      </sect1>

      <sect1 id="s1.ref.design_issues_inheritance">

        <title>Inheritance</title>

        <para>Critics concerning generalization and specialization in 
        ArgoUML.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2>

          <title>Revise Attribute Names to Avoid Conflict</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrAttrNameConflict"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrCircularInheritance">

          <title>Remove &lt;class&gt;&apos;s Circular 
          Inheritance</title>

          <para>Suggestion that a class inherits from itself, through a 
          chain of generalizations, which is not permitted.</para>

          <caution>

            <para>This critic is marked inactive by default in the 
            current release of ArgoUML (the only one so marked). It 
            will not trigger unless made active.</para>

          </caution>

        </sect2>

        <sect2>

          <title>Class Must be Abstract</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrClassMustBeAbstract"/>
          ).</para>

        </sect2>

        <sect2 id="critics.CrFinalSubclassed">

          <title>Remove final keyword or remove subclasses</title>

          <para>Suggestion that a class that is final has 
          specializations, which is not permitted in UML.</para>

        </sect2>

        <sect2 id="critics.CrIllegalGeneralization">

          <title>Illegal Generalization</title>

          <para>Suggestion that there is a generalization between 
          model elements of different UML metaclasses, which is not 
          permitted.</para>

          <caution>

            <para>It is not clear that such a generalization can be 
            created within ArgoUML. It probably indicates that the 
            diagram was created by loading a corrupt project, with an 
            XMI file describing such a generalization, possibly created 
            by a tool other than ArgoUML.</para>

          </caution>

        </sect2>

        <sect2 id="critics.CrAlreadyRealizes">

          <title>Remove Unneeded Realizes from &lt;class&gt;</title>

          <para>Suggestion that the specified class has a realization 
          relationship both directly and indirectly to the same 
          interface (by realization from two interfaces, one of which 
          is a generalization of the other for example). Good design 
          deprecates such duplication.</para>

        </sect2>

        <sect2 id="critics.CrUselessAbstract">

          <title>Define Concrete (Sub)Class</title>

          <para>Suggestion that a class is abstract with no concrete 
          subclasses, and so can never be realized.</para>

        </sect2>

        <sect2 id="critics.CrUselessInterface">

          <title>Define Class to Implement &lt;interface&gt;</title>

          <para>Suggestion that the interface referred to has no 
          influence on the running system, since it is never 
          implemented by a class.</para>

        </sect2>

        <sect2>

          <title>Change Multiple Inheritance to interfaces</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrMultipleInheritance"/>
          ).</para>

        </sect2>

        <sect2>

          <title>Make Edge More Visible</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrZeroLengthEdge"/>
          ).</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.design_issues_containment">

        <title>Containment</title>

        <para>Critics concerning containment in ArgoUML, that is where 
        one model element forms a component part of another.</para>

        <para>The current version of ArgoUML has the following critics 
        in this category.</para>

        <sect2 id="critics.CrCircularComposition">

          <title>Remove Circular Composition</title>

          <para>Suggestion that there is a series of composition 
          relationships (associations with black diamonds) that form a 
          cycle, which is not permitted.</para>

        </sect2>

        <sect2 id="critics.CrDupParamName">

          <title>Duplicate Parameter Name</title>

          <para>Suggestion that a parameter list to an operation or 
          event has two or more parameters with the same name, which is 
          not permitted.</para>

        </sect2>

        <sect2 id="critics.CrMultipleAgg">

          <title>Two Aggregate Ends (Roles) in Binary 
          Association</title>

          <para>Only one end (role) of a binary association can be 
          aggregate or composite. This a well-formedness rule of the 
          UML 1.4 standard.</para>

          <para>Aggregation and composition are used to indicate 
          whole-part relationships, and by definition, the 
          <quote>part</quote> end cannot be aggregate.</para>

          <para>To fix this, identify the <quote>part</quote> end of 
          the association, and use the critic wizard (the <literal>
          Next&gt;</literal> button, or manually set its aggregation to 
          <literal>none</literal> using the button&nbsp;2 pop-up menu or the 
          property sheet.</para>

          <para>Composition (more correctly called composite 
          aggregation) is used where there is a whole-part relationship 
          that is one-to-one or one-to-many, and the lifetime of the 
          part is inextricably tied to the lifetime of the whole. 
          Instances of the whole will have responsibility for creating 
          and destroying instances of the associated part. This also 
          means that a class can only be a part in one composite 
          aggregation.</para>

          <para>An example of a composite aggregation might be a 
          database of cars and their wheels. This is a one-to-four 
          relationship, and the database entry for a wheel is 
          associated with its car. When the car ceases to exist in the 
          database, so do its wheels.</para>

          <para>Aggregation (more correctly called shared aggregation) 
          is used where there is a whole-part relationship, that does 
          not meet the criteria for a composite aggregation. An example 
          might be a database of university courses and the students 
          that attend them. There is a whole-part relationship between 
          courses and students. However there is no lifetime 
          relationship between students and course (a student continues 
          to exist even after a course is finished) and the 
          relationship is many-to-many.</para>

        </sect2>

        <sect2 id="critics.CrNWayAgg">

          <title>Aggregate End (Role) in 3-way (or More) 
          Association</title>

          <para>Three-way (or more) associations can not have aggregate 
          ends (roles). This a well-formedness rule of the UML 1.4 
          standard.</para>

          <para>Aggregation and composition are used to indicate 
          whole-part relationships, and by definition can only apply to 
          binary associations between model elements.</para>

          <para>To fix this, manually select the association, and set 
          the aggregation of each of its ends (roles) to <literal>
          none</literal> using the button&nbsp;2 pop-up menu or the property 
          sheet.</para>

        </sect2>

        <sect2>

          <title>Wrap DataType</title>

          <para>This critic is discussed under an earlier design issues 
          category (see <xref linkend="critics.CrNonAggDataType"/>
          ).</para>

        </sect2>

      </sect1>

    </chapter>

  </part>

  <part>

    <title>Model Reference</title>

    <chapter id="ch.ref.entities">

      <title>Top Level Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within ArgoUML. The chapter covers top-level 
        <quote>general</quote> model elements. The following chapters (see 
        <xref linkend="ch.ref.entusecase"/> through 
        <xref linkend="ch.ref.entdeploy"/>) cover each of the ArgoUML 
        diagrams.</para>

        <para>There is a close relationship between this material and 
        the properties tab of the details pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        properties in general, in this chapter they are linked to 
        specific model elements.</para>

      </sect1>

      <sect1 id="s1.ref.model">

        <title>The Model</title>

        <indexterm><primary>Model, The</primary></indexterm>
        <para>The model is the top level model element within ArgoUML. In 
        the UML meta-model it is a sub-class of package. In many 
        respects within ArgoUML it behaves similarly to a package (see 
        <xref linkend="s1.ref.package"/>).</para>

        <note>

          <para>ArgoUML is restricted to one model within the 
          tool.</para>

        </note>

        <para>Standard data types, classes and packages are loaded (the 
        default, see <xref linkend="ch.ref.entbuiltin"/>) as 
        sub-packages of the model. These sub-packages are not initially 
        present in the model but are added to the model when 
        used.</para>

        <sect2>

          <title>Model Details Tabs</title>

          <indexterm><primary>Model Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Model</secondary></indexterm>
          <para>The details tabs that are active for the model are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.model_property_toolbar"/> and 
                <xref linkend="s2.ref.model_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. 
                This contains a a list of the stereotypes 
                applied to this model, and a list of
                available stereotypes that may be applied to the model.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML meta-model, <literal>
                Model</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>).</para>

                    <para>Values <literal>true</literal>, meaning the 
                    class is redundant &mdash; it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <para>Derived models have their value in analysis 
                    to introduce useful names or concepts, and in 
                    design to avoid re-computation.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.model_property_toolbar">

          <title>Model Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the composition structure of the 
                model.</para>

                <para>Since the model is the top package nothing can 
                happen, and this button is allways downlighted.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/package.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Package</literal></term>

              <listitem>

                <indexterm><primary>Add Package</primary></indexterm>
                <indexterm><primary>New Package</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Package</secondary></indexterm>
                <para>This creates a new Package (see 
                <xref linkend="s1.ref.package"/>) within the model 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that package.</para>

                <tip>

                  <para>While it can make sense to create Packages of 
                  the model this way, it is usually a lot clearer to 
                  create them within diagrams where you want 
                  them.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New DataType</literal></term>

              <listitem>

                <indexterm><primary>Add DataType</primary></indexterm>
                <indexterm><primary>New DataType</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>DataType</secondary></indexterm>
                <para>This creates a new DataType (see 
                <xref linkend="s1.ref.datatype"/>) within the model 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that DataType.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Enumeration</literal></term>

              <listitem>

                <indexterm><primary>Add Enumeration</primary></indexterm>
                <indexterm><primary>New Enumeration</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Enumeration</secondary></indexterm>
                <para>This creates a new Enumeration (see 
                <xref linkend="s1.ref.enumeration"/>) within the model 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that Enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) within the model, 
                navigating immediately to the properties tab for that 
                stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This tool is always downlighted, since it is 
                meaningless to delete the model!</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.model_property_fields">

          <title>Property Fields For The Model</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Model Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Text box. The name of the model. The name of a 
                model, like all packages, is by convention all lower 
                case.</para>

                <note>

                  <para>The default name supplied to a new model by 
                  ArgoUML, <literal>untitledModel</literal>, is thus 
                  erroneous and guarantees that ArgoUML always starts 
                  up with at least one problem being reported by the 
                  design critics.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Model 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Drop down selector. Model is provided by default 
                with the UML standard stereotypes for model (
                <literal>systemModel</literal> and <literal>
                metamodel</literal>) and package (
                <literal>facade</literal>, <literal>
                framework</literal>, <literal>stub</literal>).</para>

                <para>Stereotyping models is a useful thing, although 
                it is of limited value in ArgoUML where you have only a 
                single model.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Model 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Text box. Records the namespace for the model. 
                This is the package hierarchy. However since the model 
                is at the top of the hierarchy in ArgoUML, this box is 
                always empty.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Model 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>,  
                <literal>protected</literal>, and 
                <literal>package</literal>.</para>

                <para>Records the visibility for the model. Since 
                ArgoUML only permits one model, this has no meaningful 
                use.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Model 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>abstract</literal> is used to 
                    declare that this model cannot be instantiated, but 
                    must always be specialized.</para>

                    <para>The meaning of <literal>abstract</literal> 
                    applied to a model is not that clear. It might mean 
                    that the model contains interfaces or abstract 
                    classes without realizations. Since ArgoUML only 
                    permits one model, this is not a meaningful box to 
                    check.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    model can have no further subpackages, while 
                    <literal>root</literal> indicates it is the top 
                    level model.</para>

                    <para>Within ArgoUML <literal>root</literal> only 
                    meaningfully applies to the Model, since all 
                    packages sit within the model. In the absence of 
                    the <literal>topLevel</literal> stereotype, this 
                    could be used to emphasize that the Model is at the 
                    top level.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any model that 
                <emphasis>generalizes</emphasis> this model.</para>

                <note>

                  <para>Since there is only one model in ArgoUML there 
                  is no sensible specialization or generalization that 
                  could be created.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized model (i.e. for 
                which this model is a generalization.</para>

                <note>

                  <para>Since there is only one model in ArgoUML there 
                  is no sensible specialization or generalization that 
                  could be created.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owned Elements</literal></term>

              <listitem>

                <indexterm><primary>Model Owned 
                Elements</primary></indexterm>
                <indexterm><primary>Owned 
                Elements</primary><secondary>of 
                Model</secondary></indexterm>
                <para>Text area. A listing of the top level packages, 
                classes, interfaces, datatypes, actors, use cases, 
                associations, generalizations, and stereotypes within 
                the model.</para>

                <para>Button&nbsp;1 double click on any of the model elements 
                yields navigating to that model element.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.datatype">

        <title>Datatype</title>

        <indexterm><primary>Datatype</primary></indexterm>
        <para>Datatypes can be thought of as simple classes. They have 
        no attributes, and any operations on them must have no 
        side-effects. A useful analogy is primitive datatypes in a 
        language like Java. The integer <quote>3</quote> stands on its 
        own&mdash;it has no inner structure. There are operations (for 
        example addition) on the integers, but when I perform <literal>
        3&nbsp;+&nbsp;4</literal> the result is a new number, <quote>3</quote> 
        and <quote>4</quote> are unchanged by the exercise.</para>

        <para>Within UML&nbsp;1.4, <literal>DataType</literal> is a 
        sub-class of the <literal>Classifier</literal> metaclass. It 
        embraces the predefined primitive types (
        <literal>byte</literal>, <literal>char</literal>, <literal>
        double</literal>, <literal>float</literal>, <literal>
        int</literal>, <literal>long</literal> and <literal>
        short</literal>), the predefined enumeration, <literal>
        boolean</literal> and user defined <emphasis>enumeration 
        types</emphasis>.</para>

        <note>

          <para>Also <literal>void</literal> is implemented as a 
          datatype within ArgoUML</para>

        </note>

        <para>Within ArgoUML new datatypes may be created using the 
        <literal>New datatype</literal> button on the property tabs of 
        the model and packages (in which case the new datatype is 
        restricted in scope to the package), as well as the properties 
        tab for datatype. 
        Datatypes can also be created with the tool 
        in the diagram toolbar of a class diagram.</para>

        <para>The UML&nbsp;1.4 standard 
        allows user defined datatypes to be placed on 
        class diagrams to define their inheritence structure. 
        This is also possible in ArgoUML.
        It is represented on the diagram by a box with two compartments, of
        which the top one is marked with 
        <literal>&laquo;datatype&raquo;</literal>, 
        and contains the name. 
        The lower one contains operations.
        </para>

        <sect2>

          <title>Datatype Details Tabs</title>

          <indexterm><primary>Datatype Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Datatype</secondary></indexterm>
          <para>The details tabs that are active for datatypes are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <indexterm><primary>Datatype 
                Properties</primary></indexterm>
                <indexterm><primary>Properties</primary><secondary>of 
                Datatype</secondary></indexterm>
                <para>See 
                <xref linkend="s2.ref.datatype_property_toolbar"/> and 
                <xref linkend="s2.ref.datatype_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. Unused. One would expect a class 
                declaration for the new datatype to support code 
                generation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Datatype Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Datatype</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Datatype</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                    <tip>

                      <para>Since user defined datatypes are 
                      enumerations, they have no state to preserve, and 
                      the value of this tagged value is 
                      irrelevant.</para>

                    </tip>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    datatype.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the class 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <tip>

                      <para>While formally available, a derived 
                      datatype does not have an obvious value, and so 
                      datatypes should always be marked with <literal>
                      derived=false</literal>.</para>

                    </tip>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.datatype_property_toolbar">

          <title>Datatype Property Toolbar</title>

          <indexterm><primary>Datatype Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Datatype</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New datatype</literal></term>

              <listitem>

                <para>This creates a new datatype (see 
                <xref linkend="s1.ref.class_class"/>) within the same 
                package as the current datatype.</para>

                <tip>

                  <para>While it can make sense to create datatypes 
                  this way, it can be clearer to create them within the 
                  package or model where you want them.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Enumeration</literal></term>

              <listitem>

                <indexterm><primary>Add Enumeration</primary></indexterm>
                <indexterm><primary>New Enumeration</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Enumeration</secondary></indexterm>
                <para>This creates a new Enumeration (see 
                <xref linkend="s1.ref.enumeration"/>) 
                in the same package as the datatype, 
                navigating immediately 
                to the properties tab for that Enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Operation</literal></term>

              <listitem>

                <para>This creates a new operation within the datatype, 
                navigating immediately to the properties tab for that 
                operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) within the same 
                package as the datatype, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the datatype from the model.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.datatype_property_fields">

          <title>Property Fields For Datatype</title>

          <indexterm><primary>Datatype Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Datatype</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Datatype Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Datatype</secondary></indexterm>
                <para>Text box. The name of the datatype. The primitive 
                datatypes all have lower case names, but there is no 
                formal convention.</para>

                <note>

                  <para>The default name supplied for a newly created 
                  datatype is the empty string <quote />. Datatypes 
                  with empty string names will appear with the name 
                  <literal>(Unnamed Datatype)</literal> in the 
                  explorer.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector with navigate button. 
                Allows changing the 
                namespace for the datatype. This is the package 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Datatype 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Datatype</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this datatype cannot be instantiated, 
                    but must always be specialized.</para>

                    <note>

                      <para>ArgoUML provides no mechanism for 
                      specializing datatypes, so this check box is of 
                      little use.</para>

                    </note>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    datatype can have no further sub-types, while 
                    <literal>Root</literal> indicates it is a top level 
                    datatype.</para>

                    <tip>

                      <para>You can define the specialization of 
                      datatypes in a class diagram 
                      by drawing generalizations between them.</para>

                    </tip>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Datatype 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Datatype</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal>, and
                <literal>package</literal>.</para>

                <para>Records the visibility for the Datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Client Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists any elements that depend on this 
                datatype.</para>

                <caution>

                  <para>It is not clear that dependencies between 
                  datatypes makes much sense.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Supplier Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists any elements that this datatype 
                depends on.</para>

                <caution>

                  <para>It is not clear that dependencies between 
                  datatypes makes much sense.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any datatype that 
                <emphasis>generalizes</emphasis> this datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized datatype (i.e. 
                for which this datatype is a generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Text area. Lists all the operations defined on 
                this datatype. Button&nbsp;1 double click navigates to the 
                selected operation. button&nbsp;2 click brings up a pop up 
                menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more operations, and the 
                    operation selected is not at the top. It is moved 
                    up one.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the bottom. It is 
                    moved down one.</para>

                  </listitem>

                </itemizedlist>

                <para>See <xref linkend="s1.ref.operation"/> for 
                details of operations.</para>

                <caution>

                  <para>ArgoUML treats all operations as equivalent. 
                  Any operations created here will use the same 
                  mechanism as operations for classes. Remember that 
                  operations on datatypes must have no side effects 
                  (they are read-only). This means the <literal>
                  query</literal> modifier <emphasis>must</emphasis> be 
                  checked for all operations.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.enumeration">

        <title>Enumeration</title>

        <indexterm><primary>Enumeration</primary></indexterm>
        <para>An enumeration is a primitive datatype 
        that can have a fixed short list of values. 
        It has no attributes, 
        and any operations on them must have no 
        side-effects. A useful analogy is the primitive datatype
        boolean in a language like Java.
        The boolean stands on its 
        own&mdash;it has no inner structure. 
        There are operations (for 
        example logical xor) on the booleans, but when I perform <literal>
        true xor true</literal> the result is a new boolean, 
        and the original 2 booleans <quote>true</quote> 
        are unchanged by the exercise.</para>

        <para>Within UML&nbsp;1.4, <literal>Enumeration</literal> is a 
        sub-class of the <literal>DataType</literal> metaclass.  
        </para>

        <para>The big difference with other DataTypes, is that an
        Enumeration has <literal>EnumerationLiteral</literal>s. 
        E.g. the Enumeration <quote>boolean</quote> is defined as
        having 2 EnumerationLiterals, <quote>true</quote> and
        <quote>false</quote>.
        </para>

        <para>Within ArgoUML new enumerations may be created using the 
        <literal>New Enumeration</literal> button on the property tabs of 
        the model and packages (in which case the new enumeration is 
        restricted in scope to the package), as well as the properties 
        tab for datatype and enumeration. 
        Enumerations can also be created with the tool 
        in the diagram toolbar of a class diagram.
        </para>

        <para>The UML&nbsp;1.4 standard allows user defined 
          enumerations to be placed on class diagrams 
          to define their inheritence structure. 
          This is also possible in ArgoUML. 
          It is represented on the diagram by a box 
          with three compartments, 
          of which the top one is marked with 
          <literal>&laquo;enumeration&raquo;</literal>, 
          and contains the name. 
          The middle compartment shows the enumeration literals.
          The lower one contains operations.
        </para>

        <sect2>

          <title>Enumeration Details Tabs</title>

          <indexterm><primary>Enumeration Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Enumeration</secondary></indexterm>
          <para>The details tabs that are active for enumerations are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <indexterm><primary>Enumeration 
                Properties</primary></indexterm>
                <indexterm><primary>Properties</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>See 
                <xref linkend="s2.ref.enumeration_property_toolbar"/> and 
                <xref linkend="s2.ref.enumeration_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. 
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. 
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. The UML metamodel has the following 
                stereotypes defined by default for a Classifier, 
                which also apply to an Enumeration: 
                </para>
                
                <itemizedlist>

                  <listitem>
                    <para><literal>metaclass</literal> (from the 
                    superclass, <literal>Classifier</literal>). 
                    <!-- TODO: Not present! -->
                    </para>
                  </listitem>

                  <listitem>
                    <para><literal>powertype</literal> (from the 
                    superclass, <literal>Classifier</literal>). 
                    <!-- TODO: Not present! -->
                    </para>
                  </listitem>

                  <listitem>
                    <para><literal>process</literal> (from the 
                    superclass, <literal>Classifier</literal>). 
                    </para>
                  </listitem>

                  <listitem>
                    <para><literal>thread</literal> (from the 
                    superclass, <literal>Classifier</literal>). 
                    </para>
                  </listitem>

                  <listitem>
                    <para><literal>utility</literal> (from the 
                    superclass, <literal>Classifier</literal>). 
                    </para>
                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Enumeration Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Enumeration</literal> has no standard tagged 
                values defined.</para>


              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.enumeration_property_toolbar">

          <title>Enumeration Property Toolbar</title>

          <indexterm><primary>Enumeration Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Enumeration</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the composition structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New datatype</literal></term>

              <listitem>

                <para>This creates a new datatype (see 
                <xref linkend="s1.ref.class_class"/>) within the same 
                package as the current enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New enumeration</literal></term>

              <listitem>

                <para>This creates a new enumeration within the 
                same namespace as the current enumeration, 
                navigating immediately to the properties tab 
                for new enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration_literal.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New enumeration literal</literal></term>

              <listitem>

                <para>This creates a new enumeration literal within the 
                enumeration, navigating immediately to the properties tab 
                for that literal.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Operation</literal></term>

              <listitem>

                <para>This creates a new operation within the enumeration, 
                navigating immediately to the properties tab for that 
                operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) within the same 
                package as the enumeration, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the datatype from the model.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.enumeration_property_fields">

          <title>Property Fields For Enumeration</title>

          <indexterm><primary>Enumeration Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Enumeration</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Enumeration Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>Text box. The name of the enumeration. The primitive 
                enumerations all have lower case names, but there is no 
                formal convention.</para>

                <note>

                  <para>The default name supplied for a newly created 
                  datatype is the empty string <quote />. Enumerations 
                  with empty string names will appear with the name 
                  <literal>(Unnamed Enumeration)</literal> in the 
                  explorer.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector with navigation button. 
                Allows changing the 
                namespace for the enumeration. This is the composition 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Enumeration 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this enumeration cannot be instantiated, 
                    but must always be specialized.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    enumeration can have no further sub-types, while 
                    <literal>Root</literal> indicates it is a top level 
                    enumeration.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Enumeration 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal>, and
                <literal>package</literal>.</para>

                <para>Records the visibility for the Enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Client Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists any elements that depend on this 
                enumeration. Button&nbsp;1 double click navigates to the 
                selected modelelement. Button&nbsp;2 click brings up a pop up 
                menu with following entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add...</literal>. 
                    This brings up a dialog box 
                    that allows to create dependencies 
                    from other modelelements.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Supplier Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists any elements that this enumeration 
                depends on. Button&nbsp;1 double click navigates to the 
                selected modelelement. Button&nbsp;2 click brings up a pop up 
                menu with the following entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add...</literal>. 
                    This brings up a dialog box 
                    that allows to create dependencies 
                    to other modelelements.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any enumeration that 
                <emphasis>generalizes</emphasis> this enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized enumerations (i.e. 
                for which this enumeration is a generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Text area. Lists all the operations defined on 
                this enumeration. Button&nbsp;1 double click navigates to the 
                selected operation. Button&nbsp;2 click brings up a pop up 
                menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more operations, and the 
                    operation selected is not at the top. It is moved 
                    up one.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the bottom. It is 
                    moved down one.</para>

                  </listitem>

                </itemizedlist>

                <para>See <xref linkend="s1.ref.operation"/> for 
                details of operations.</para>

                <caution>

                  <para>ArgoUML treats all operations as equivalent. 
                  Any operations created here will use the same 
                  mechanism as operations for classes. Remember that 
                  operations on enumerations must have no side effects 
                  (they are read-only). This means the <literal>
                  query</literal> modifier <emphasis>must</emphasis> be 
                  checked for all operations.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Literals</literal></term>

              <listitem>

                <indexterm><primary>Enumeration 
                Literals</primary></indexterm>
                <indexterm><primary>Literals</primary><secondary>of 
                Enumeration</secondary></indexterm>
                <para>Text area. Lists all the enumeration literals 
                defined for this enumeration. Button&nbsp;1 double click 
                navigates to the selected literal, button&nbsp;2 click 
                brings up a pop up menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more literals, and the 
                    literal selected is not at the top. It is moved up 
                    one.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more literals listed, and 
                    the literal selected is not at the bottom. It is 
                    moved down one.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.enumeration-literal">
        <title>Enumeration Literal</title>
        <indexterm><primary>Enumeration Literal</primary></indexterm>
        <para>An enumeration literal is one of the predefined values 
        of an Enumeration.</para>
      </sect1>

      <sect1 id="s1.ref.stereotype">

        <title>Stereotype</title>

        <indexterm><primary>Stereotype</primary></indexterm>
        <para>Stereotypes are the main extension mechanism of UML, 
        providing a way to derive specializations of the standard 
        metaclasses. <literal>Stereotype</literal> is a sub-class of 
        <literal>GeneralizableElement</literal> in the UML metamodel. 
        Stereotypes are supplemented by 
        <emphasis>constraints</emphasis> and <emphasis>tagged 
        values</emphasis>.</para>

        <para>New stereotypes are added from the property tab of almost 
        any model element. Properties of existing stereotypes can be reached 
        by selecting the property tab for any model element with that 
        stereotype and using the navigate button (
        <guiicon><inlinemediaobject><imageobject>
        <imagedata align="center"
         fileref="images/icons/navigate_stereotype.gif"
         format="GIF"/></imageobject></inlinemediaobject></guiicon>) 
        within the property tab.</para>

        <sect2>

          <title>Stereotype Details Tabs</title>

          <indexterm><primary>Stereotype Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Stereotype</secondary></indexterm>
          <para>The details tabs that are active for stereotypes are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.stereotype_property_toolbar"/> 
                and <xref linkend="s2.ref.stereotype_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <warning>

                  <para>Here you can set stereotypes of stereotypes, 
                  not a very usefull thing to do.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Stereotype</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the class 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>This indicates any element with this 
                      stereotype has the <literal>derived</literal> tag 
                      set accordingly.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <caution>

                  <para>Tagged values for a stereotype are rather 
                  different to those for elements in the UML core 
                  architecture, in that they apply to all model elements to 
                  which the stereotype is applied, 
                  <emphasis>not</emphasis> just the stereotype 
                  itself.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.stereotype_property_toolbar">

          <title>Stereotype Property Toolbar</title>

          <indexterm><primary>Stereotype Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Stereotype</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Add stereotype</literal></term>

              <listitem>

                <para>This creates a new stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) within the model 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/tag_definition.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Tag Definition</literal></term>

              <listitem>

                <para>This creates a new tag definition (see 
                <xref linkend="s1.ref.tagdefinition"/>) within the model 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that tagdefinition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the stereotype from the model.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.stereotype_property_fields">

          <title>Property Fields For Stereotype</title>

          <indexterm><primary>Stereotype Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Stereotype</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Stereotype 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Stereotype</secondary></indexterm>
                <para>Text box. The name of the stereotype. There is no 
                convention for naming stereotypes, beyond starting them 
                with a lower case letter. Even the standard UML 
                stereotypes vary between all lower case (e.g. <literal>
                metamodel</literal>), bumpy caps (e.g. <literal>
                systemModel</literal>) and space separated (e.g. 
                <literal>object model</literal>).</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for stereotypes</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base Class</literal></term>

              <listitem>

                <indexterm><primary>Stereotype Base 
                Class</primary></indexterm>
                <indexterm><primary>Base Class</primary><secondary>of 
                Stereotype</secondary></indexterm>
                <para>Drop down selector. Any stereotype must be 
                derived from one of the metaclasses in the UML 
                metamodel <!--
                <literal>Abstraction</literal>, <literal>
                Actor</literal>, <literal>Association</literal>, 
                <literal>AssociationEnd</literal>, <literal>
                Attribute</literal>, <literal>
                BehavioralFeature</literal>, <literal>
                CallEvent</literal>, <literal>Class</literal>, <literal>
                Classifier</literal>, <literal>Collaboration</literal>, 
                <literal>Comment</literal>, <literal>
                Component</literal>, <literal>Constraint</literal>, 
                <literal>DataType</literal>, <literal>
                Exception</literal>, <literal>Flow</literal>, <literal>
                Generalization</literal>, <literal>Interface</literal>, 
                <literal>Link</literal>, <literal>Model</literal>, 
                <literal>ModelElement</literal>, <literal>
                Node</literal>, <literal>NodeInstance</literal>, 
                <literal>ObjectFlowState</literal>, <literal>
                Operation</literal>, <literal>Package</literal>, 
                <literal>Permission</literal>, <literal>
                Signal</literal>, <literal>Subsystem</literal> and 
                <literal>Usage</literal>) -->
                or the model element classes that 
                derive from them. The stereotype will then be available 
                to model elements that derive from that same metaclass or 
                that model element.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Stereotype 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Stereotype</secondary></indexterm>
                <para>Drop down selector with navigation button. 
                Records the namespace for the stereotype. 
                This is the package hierarchy.</para>
 
              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Stereotype 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Stereotype</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that model elements that use this stereotype 
                    cannot be instantiated, but must always be 
                    specialized.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that 
                    model elements that use this stereotype can have no 
                    further sub-types, while <literal>Root</literal> 
                    indicates it is a top level model element.</para>

                  </listitem>

                </itemizedlist>

                <caution>

                  <para>Remember that these modifiers apply to the 
                  model elements using the stereotype, not just the 
                  stereotype.
                  <!-- TODO: MVW: I strongly doubt this. 
                  The standard says: "Tag definitions and constraints 
                  attached to a stereotype apply to all model elements 
                  branded by that stereotype." 
                  But it does not say the same for modifiers. -->
                  </para>

                </caution>

                <warning>

                  <para>ArgoUML neither imposes, nor checks that 
                  model elements using a stereotype adopt the 
                  stereotype&apos;s modifiers.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>
              <term><literal>Visibility</literal></term>
              <listitem>
                <indexterm><primary>Stereotype 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Stereotype</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal>, and
                <literal>package</literal>.</para>

                <para>Records the visibility for the stereotype.</para>

              </listitem>
            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any stereotype that 
                <emphasis>generalizes</emphasis> this stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text area. Lists any specialized stereotype (i.e. 
                for which this stereotype is a generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tag Definitions</literal></term>

              <listitem>

                <para>Text area. Lists any tag definitions 
                that are defined for this stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Extended Elements</literal></term>

              <listitem>

                <para>Text area. Lists all modelelements 
                that are stereotyped by this stereotype.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.tagdefinition">

        <title>Tag Definition</title>
        
        <para>(To Be Written)</para>
        
      </sect1>

      <sect1 id="s1.ref.diagram_types">

        <title>Diagram</title>

        <indexterm><primary>Diagram</primary></indexterm>
        <para>The UML standard specifies eight principal diagrams, all 
        of which are supported by ArgoUML.</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Use case diagram</emphasis>. Used to 
            capture and analyse the requirements for any OOA&amp;D 
            project. See <xref linkend="ch.ref.entusecase"/> for 
            details of the ArgoUML use case diagram and the model elements 
            it supports.</para>

          </listitem>

          <listitem>

            <para><emphasis>Class diagram</emphasis>. This diagram 
            captures the static structure of the system being designed, 
            showing the classes, interfaces and datatypes and how they 
            are related. Variants of this diagram are used to show 
            package structures within a system (the <emphasis>package 
            diagram</emphasis>) and the relationships between 
            particular instances (the <emphasis>object 
            diagram</emphasis>).</para>

            <para>The ArgoUML class diagram provides support for class 
            and package diagrams. See <xref linkend="ch.ref.entclass"/> 
            for details of the model elements it supports. The object 
            diagram is suported on the Deployment diagram.</para>

          </listitem>

          <listitem>

            <para><emphasis>Behavior diagrams</emphasis>. There are 
            four such diagrams (or strictly speaking, five, since the 
            use case diagram is a type of behavior diagram), which show 
            the dynamic behavior of the system at all levels.</para>

            <itemizedlist>

              <listitem>

                <para><emphasis>Statechart diagram</emphasis>. Used to 
                show the dynamic behavior of a single object (class 
                instance). This diagram is of particular use in systems 
                using complex communication protocols, such as in 
                telecommunications. See 
                <xref linkend="ch.ref.entstate"/> for details of the 
                ArgoUML statechart diagram and the model elements it 
                supports.</para>

              </listitem>

              <listitem>

                <para><emphasis>Activity diagram</emphasis>. Used to 
                show the dynamic behavior of groups of objects (class 
                instance). This diagram is an alternative to the 
                statechart diagram, and is better suited to systems 
                with a great deal of user interaction. See 
                <xref linkend="ch.ref.entactiv"/> for details of the 
                ArgoUML activity diagram and the model elements it 
                supports.</para>

              </listitem>

              <listitem>

                <para><emphasis>Interaction diagrams</emphasis>. There 
                are two diagrams in this category, used to show the 
                dynamic interaction between objects (class instances) 
                in the system.</para>

                <itemizedlist>

                  <listitem>

                    <para><emphasis>Sequence diagram</emphasis>. Shows 
                    the interactions (typically messages or procedure 
                    calls) between instances of classes (objects) and 
                    actors against a timeline. Particularly useful 
                    where the timing relationships between interactions 
                    are important. See <xref linkend="ch.ref.entseq"/> 
                    for details of the ArgoUML sequence diagram and the 
                    model elements it supports.</para>

                  </listitem>

                  <listitem>

                    <para><emphasis>Collaboration diagram</emphasis>. 
                    Shows the interactions (typically messages or 
                    procedure calls) between instances of classes 
                    (objects) and actors against the structural 
                    relationships between those instances. Particularly 
                    suitable where it is useful to relate interactions 
                    to the static structure of the system. See 
                    <xref linkend="ch.ref.entcollab"/> for details of 
                    the ArgoUML collaboration diagram and the model elements 
                    it supports.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </itemizedlist>

          </listitem>

          <listitem>

            <para><emphasis>Implementation diagrams</emphasis>. UML 
            defines two implementation diagrams to show the 
            relationship between the software components that make up a 
            system (the <emphasis>component diagram</emphasis>) and the 
            relationship between the software and the hardware on which 
            it is deployed at run-time (the <emphasis>deployment 
            diagram</emphasis>.</para>

            <para>The ArgoUML deployment diagram provides support for 
            both component and deployment diagrams, and additionally 
            for object diagrams. See <xref linkend="ch.ref.entdeploy"/> 
            for details of the diagram and the model elements it 
            supports.</para>

          </listitem>

        </itemizedlist>

        <para>Diagrams are created using the <literal>Create</literal> 
        drop down menu (see <xref linkend="s1.ref.create.diagram.menu"/>
        ), or with the tools on the toolbar (see 
        <xref linkend="ch.ref.toolbar.create"/>),
        or with the pop-up menus in the explorer.</para>

        <note>

          <para>ArgoUML uses its deployment diagram to create the UML 
          1.4 component, deployment and object diagrams.</para>

        </note>

        <caution>

          <para>Statechart and activity diagrams are associated with a 
          particular class or operation (or the latter also with a 
          package), and can only be created when this modelelement has 
          been selected.</para>

        </caution>

        <warning>

          <para>In ArgoUML version 0.26, the UML 1.4 object diagram as 
          a variant of the class diagram is not directly supported. 
          However, it is possible to create object diagrams 
          within the ArgoUML deployment diagram.</para>

        </warning>

        <sect2>

          <title>Diagram Details Tabs</title>

          <indexterm><primary>Diagram Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Diagrams</secondary></indexterm>
          <para>The details tabs that are active for diagrams are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.diagram_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2>

          <title>Diagram Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the diagram from the model. As a 
                consequence, in case of a statechart diagram or an 
                activity diagram, all contained elements are deleted, 
                too.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.diagram_property_fields">

          <title>Property Fields For Diagram</title>

          <indexterm><primary>Diagram Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Diagrams</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Diagram Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Diagrams</secondary></indexterm>
                <para>The name of the diagram. There are no conventions 
                for naming diagrams. By default, ArgoUML uses the 
                (space separated) diagram name and a sequence number, 
                thus <literal>Use Case Diagram 1</literal>.</para>

                <tip>

                  <para>This name is used to generate a filename when 
                  activating the <quote>Save Graphics...</quote> 
                  menu-item.</para>

                </tip>

              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>Home Model</literal></term>
              <listitem>

                <indexterm><primary>Home Model</primary></indexterm>
                <indexterm><primary>Home Model</primary><secondary>of 
                Diagrams</secondary></indexterm>
                <para>The Home Model of the diagram
                is not something defined in the UML specification.
                The Home Model is the modelelement represented by the diagram.
                Hence its type depends on the type of diagram: e.g. 
                it is the namespace represented by a class diagram, 
                or the statemachine in case of a Statechart diagram.
                </para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entusecase">

      <title>Use Case Diagram Model Element Reference</title>

      <indexterm><primary>Use Case Diagram</primary></indexterm>
      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a use case diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>There is a close relationship between this material and 
        the properties tab of the details pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <para><xref linkend="fig.ref.use_case_diagram"/> shows a use 
        case diagram with all typical model elements displayed.</para>

        <figure float="1" id="fig.ref.use_case_diagram">

          <title>Typical model elements on a use case diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/use_case_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>ArgoUML Limitations Concerning Use Case 
          Diagrams</title>

          <para>Use case diagrams are now well supported within 
          ArgoUML. There still are some minor limitations though,
          especially with extension points.</para>

          <note>

            <para>Earlier versions of ArgoUML (0.9 and earlier) 
            implemented extend and include relationships by using a 
            stereotyped dependency relationship. Although such diagrams 
            will show correctly on the diagram, they will not link 
            correctly to the use cases, and should be replaced by 
            proper extend and include relationships using the current 
            system.</para>

          </note>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.actor">

        <title>Actor</title>

        <indexterm><primary>Actor</primary></indexterm>
        <indexterm><primary>External entity</primary></indexterm>
        <para>An actor represents any external entity (human or 
        machine) that interacts with the system, providing input, 
        receiving output, or both.</para>

        <para>Within the UML metamodel, actor is a sub-class of 
        <literal>classifier</literal>.</para>

        <para>The actor is represented by a <quote>stick man</quote> 
        figure on the diagram (see 
        <xref linkend="fig.ref.use_case_diagram"/>).</para>

        <sect2>

          <title>Actor Details Tabs</title>

          <indexterm><primary>Actor Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Actor</secondary></indexterm>
          <para>The details tabs that are active for actors are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.actor_property_toolbar"/> and 
                <xref linkend="s2.ref.actor_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The fill color is used for the 
                stick man&apos;s head.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. Usually, no code is provided for an 
                actor, since it is external to the system.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Actor</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                    <tip>

                      <para>Actors sit outside the system, and so their 
                      internal behavior is of little concern, and this 
                      tagged value is best ignored.</para>

                    </tip>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    actor.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the actor 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived actors have limited value, since 
                      they sit outside the system being designed. They 
                      may have their value in analysis to introduce 
                      useful names or concepts.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Classifier.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.actor_property_toolbar">

          <title>Actor Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/actor.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Add Actor</literal></term>

              <listitem>

                <indexterm><primary>Add Actor</primary></indexterm>
                <indexterm><primary>New Actor</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Actor</secondary></indexterm>
                <para>This creates a new actor within the model, (but 
                not within the diagram), navigating immediately to the 
                properties tab for that actor.</para>

                <tip>

                  <para>This method of creating a new actor may be 
                  confusing. It is much better to create an actor on 
                  the diagram.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>
            
              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Reception</literal></term>
            
              <listitem>

                <indexterm><primary>Add Reception</primary></indexterm>
                <indexterm><primary>New Reception</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Reception</secondary></indexterm>

                <para>This creates a new reception within the model,(but 
                not within the diagram), navigating immediately to the 
                properties tab for that rception.</para>

                <tip>

                  <para>A reception is a declaration that the actor
                  handles a signal, but the actual handling 
                  is specified by a state machine.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected actor from the 
                model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an actor from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.actor_property_fields">

          <title>Property Fields For Actor</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Actor Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Text box. The name of the actor. The diagram 
                shows this name below the stick man figure. Since an 
                actor is a classifier, it would be conventional to 
                Capitalize the first letter (and initial letters of any 
                component words), e.g. <literal>
                RemoteSensor</literal>.</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for actors</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Actor 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Text box with navigation button. 
                Records the namespace for the actor. 
                This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Actor 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this actor cannot be instantiated, but 
                    must always be specialized.</para>

                    <caution>

                      <para>While actors can be specialized and 
                      generalized, it is not clear that an abstract 
                      actor has any meaning. Perhaps it might be used 
                      to indicate an actor that does not itself 
                      interact with a use case, but whose children 
                      do.</para>

                    </caution>

                  </listitem>

                  <listitem>

                    <para><literal>leaf</literal> indicates that this 
                    actor can have no further children, while <literal>
                    Root</literal> indicates it is a top level actor 
                    with no parent.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <indexterm><primary>Actor 
                Generalizations</primary></indexterm>
                <indexterm>
                <primary>Generalizations</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Text area. Lists any actor that 
                <emphasis>generalizes</emphasis> this actor.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <indexterm><primary>Actor 
                Specializations</primary></indexterm>
                <indexterm>
                <primary>Specializations</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Text box. Lists any specialized actor (i.e. for 
                which this actor is a generalization. The specialized 
                actors can communicate with the same use case instances 
                as this actor.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association Ends</literal></term>

              <listitem>

                <indexterm><primary>Actor Association 
                Ends</primary></indexterm>
                <indexterm><primary>Association 
                Ends</primary><secondary>of 
                Actor</secondary></indexterm>
                <para>Text area. Lists any association ends of 
                associations connected to this actor.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.use_case">

        <title>Use Case</title>

        <indexterm><primary>Use Case</primary></indexterm>
        <para>A use case represents a complete meaningful 
        <quote>chunk</quote> of activity by the system in relation to 
        its external users (actors), human or machine. It represents 
        the primary route through which requirements are captured for 
        the system under construction</para>

        <para>Within the UML metamodel, use case is a sub-class of 
        <literal>classifier</literal>.</para>

        <para>The use case icon is an oval (see 
        <xref linkend="fig.ref.use_case_diagram"/>). It may be split in 
        two, with the lower compartment showing extension points</para>

        <caution>

          <para>By default ArgoUML does not show the extension point 
          compartment. It may be revealed by the context sensitive 
          <literal>Show</literal> menu (using button&nbsp;2 click), or from 
          the Presentation tab.</para>

        </caution>

        <sect2>

          <title>Use Case Details Tabs</title>

          <indexterm><primary>Use Case Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for Use 
          Case</secondary></indexterm>
          <para>The details tabs that are active for use cases are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.use_case_property_toolbar"/> and 
                <xref linkend="s2.ref.use_case_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The Fill color is used for the use 
                case oval.</para>

                <para>The <literal>Display: Extension Points</literal> 
                check box is used to control whether an extension point 
                compartment is displayed.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. It would not be usual to provide 
                any code for a use case, since it is primarily a 
                vehicle for capturing requirements about the system 
                under construction, not creating the solution.</para>

              </listitem>

            </varlistentry>
            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                UseCase</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                    <tip>

                      <para>In general the instantiation of use cases 
                      is not a major aspect of any design method (they 
                      are mostly concerned with requirements capture. 
                      For most OOA&amp;D methodologies, this tag can 
                      safely be ignored.</para>

                    </tip>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    use case.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the use 
                    case is redundant&mdash;it can be formally derived from 
                    other elements, or <literal>false</literal> meaning 
                    it cannot.</para>

                    <note>

                      <para>Derived use cases still have their value in 
                      analysis to introduce useful names or 
                      concepts.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Classifier.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.use_case_property_toolbar">

          <title>Use Case Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/use_case.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New use case</literal></term>

              <listitem>

                <indexterm><primary>Add Use Case</primary></indexterm>
                <indexterm><primary>New Use Case</primary></indexterm>
                <indexterm><primary>Create New</primary><secondary>Use 
                Case</secondary></indexterm>
                <para>This creates a new use case within the model, 
                (but not within the diagram), and shows immediately the 
                properties tab for that use case.</para>

                <tip>

                  <para>This method of creating a new use case can be 
                  confusing. It is much better to create a new use case 
                  on the diagram of your choice.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/extension_point.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New extension point</literal></term>

              <listitem>

                <indexterm><primary>Add Extension 
                Point</primary></indexterm>
                <indexterm><primary>New Extension 
                Point</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Extension 
                Point</secondary></indexterm>
                <para>This creates a new use extension point within the 
                namespace of the current use case, with the current use 
                case as its associated use case, navigating immediately 
                to the properties tab for that extension point.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Attribute</literal></term>

              <listitem>
                <para>This creates a new attribute within the 
                current use case, 
                navigating immediately 
                to the properties tab for that attribute.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Operation</literal></term>

              <listitem>
                <para>This creates a new operation within the 
                current use case, 
                navigating immediately 
                to the properties tab for that operation.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Reception</literal></term>

              <listitem>
                <para>This creates a new reception within the 
                current use case, 
                navigating immediately 
                to the properties tab for that reception.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>
                <para>This creates a new stereotype within the 
                current use case, 
                navigating immediately 
                to the properties tab for that stereotype.</para>
              </listitem>
            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected use case from the 
                model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a use case from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.use_case_property_fields">

          <title>Property Fields For Use Case</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Use Case Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text box. The name of the use case. Since a use 
                case is a classifier, it would be conventional to 
                Capitalize the first letter (and initial letters of any 
                component words), e.g. <literal>RemoteSensor</literal>. 
                The name is shown inside the oval representation of the 
                use case on the diagram.</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for use cases</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Use Case 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Use Case</secondary></indexterm>
                <para>Text box with navigation button. 
                Records the namespace for the use case. 
                This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Use Case 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Use Case</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal> <literal>Leaf</literal> and <literal>
                Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this actor cannot be instantiated, but 
                    must always be specialized. .</para>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    use case can have no further children, while 
                    <literal>Root</literal> indicates it is a top level 
                    use case with no parent.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Client Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists the <quote>depending</quote> 
                ends of the relationship, i.e. the end that makes use 
                of the other end.</para>

                <para>Button&nbsp;1 double click navigates to the dependency 
                and opens its property tab.</para>
                <para>Button&nbsp;2 click shows a pop-up menu with one entry
                <literal>Add...</literal> that
                opens a dialog box where you can add and remove 
                depending modelelements.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Supplier Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists the <quote>supplying</quote> 
                ends of the relationship, i.e. the end supplying what 
                is needed by the other end.</para>

                <para>Button&nbsp;1 double click navigates to the dependency 
                and opens its property tab.</para>
                <para>Button&nbsp;2 click shows a pop-up menu with one entry
                <literal>Add...</literal> that
                opens a dialog box where you can add and remove 
                dependent modelelements.</para>
              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>
              <anchor id="ref.use_case_generalization"/>Generalizations</literal></term>

              <listitem>

                <indexterm><primary>Use Case 
                Generalization</primary></indexterm>
                <indexterm>
                <primary>Generalizations</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text area. Lists use cases which are 
                generalizations of this one. Will be set whenever a 
                generalization is created on the from this Use Case. 
                Button&nbsp;1 Double Click on a generalization will navigate 
                to that generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <indexterm><primary>Use Case 
                Specialization</primary></indexterm>
                <indexterm>
                <primary>Specializations</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text box. Lists any specialized use case (i.e. 
                for which this use case is a generalization.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Extends</literal></term>

              <listitem>

                <indexterm><primary>Use Case Extend 
                Relationships</primary></indexterm>
                <indexterm><primary>Extend 
                Relationship</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text box. Lists any class that is extended by 
                this use case.</para>

                <para>Where an extends relationship has been created, 
                button&nbsp;1 double click will navigate to that 
                relationship.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Includes</literal></term>

              <listitem>

                <indexterm><primary>Use Case Include 
                Relationships</primary></indexterm>
                <indexterm><primary>Include 
                Relationship</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text box. Lists any use case that this use case 
                includes.</para>

                <para>Where an include relationship has been created, 
                button&nbsp;1 Double Click will navigate to that 
                relationship.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Attributes</literal></term>

              <listitem>

                <para>Text area. Lists all the attributes (see 
                <xref linkend="s1.ref.attribute"/>) defined for this 
                use case. Button&nbsp;1 double click navigates to the selected 
                attribute. Button&nbsp;2 gives a pop up menu with two 
                entries, which allow reordering the attributes.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more attributes listed, and 
                    the attribute selected is not at the top. It moves 
                    the attribute up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more attributes listed, and 
                    the attribute selected is not at the bottom. It 
                    moves the attribute down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association Ends</literal></term>

              <listitem>

                <para>Text box. Lists any association ends (see 
                <xref linkend="s1.ref.association_class"/>) of 
                associations connected to this use case.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Text area. Lists all the operations (see 
                <xref linkend="s1.ref.operation"/>) defined on this 
                use case. Button&nbsp;1 click navigates to the selected 
                operation. Button&nbsp;2 gives a pop up menu with two 
                entries, which allow reordering the operations.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the top. It moves 
                    the operation up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the bottom. It 
                    moves the operation down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>


            <varlistentry>

              <term><literal>Extension Points</literal></term>

              <listitem>

                <indexterm><primary>Use Case Extension 
                Points</primary></indexterm>
                <indexterm><primary>Extension 
                Point</primary><secondary>of Use 
                Case</secondary></indexterm>
                <para>Text box. If this use case is, or can be 
                extended, this field lists the extension points for the 
                use case.</para>

                <note>

                  <para>Extension points are listed by their location 
                  point rather than their name.</para>

                </note>

                <para>Where an extension point has been created (see 
                below), button&nbsp;1 Double Click will navigate to that 
                relationship. Button&nbsp;2 gives a pop up menu with
                the following entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new extension 
                    point and navigate to it, making this use case the 
                    owning use case of the extension point.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more extension points listed, and 
                    the extension point selected is not at the top. It moves 
                    the extension point up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more extension points listed, and 
                    the extension point selected is not at the bottom. It 
                    moves the extension point down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.extension_point">

        <title>Extension Point</title>

        <indexterm><primary>Extension Point</primary></indexterm>
        <para>An extension point describes a point in a use case where 
        an extending use case may provide additional behavior.</para>

        <para>Examples for a travel agent sales system might be the use 
        case for paying for a ticket, which has an extension point in 
        the specification of the payment. Extending use cases may then 
        extend at this point to pay by cash, credit card etc.</para>

        <para>Within the UML metamodel, <literal>Extension 
        Point</literal> is a sub-class of <literal>
        ModelElement</literal>. A use case may display an extension 
        point compartment (see <xref linkend="s1.ref.use_case"/> for 
        details), in which extension points are shown with the 
        following syntax.</para>

        <blockquote>

          <para><emphasis>name</emphasis>
          <literal>:</literal><emphasis>location</emphasis>.</para>

        </blockquote>

        <sect2>

          <title>Extension Point Details Tabs</title>

          <indexterm><primary>Extension Point Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Extension Point</secondary></indexterm>
          <para>The details tabs that are active for extension points 
          are as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.extension_point_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.extension_point_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. </para>

                <para>Extensionpoints do not have 
                any stereotypes defined by default.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                ExtensionPoint</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    extension point is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>It is not clear how derived extension 
                      points could have any value in analysis.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.extension_point_property_toolbar">

          <title>Extension Point Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up to the use case which owns this 
                extension point.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/extension_point.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Extension Point</literal></term>

              <listitem>

                <indexterm><primary>Add Extension 
                Point</primary></indexterm>
                <indexterm><primary>New Extension 
                Point</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Extension 
                Point</secondary></indexterm>
                <para>This creates a new Extension Point below the 
                selected extension point, navigating immediately to the 
                properties tab of the newly created extension 
                point.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                extension point, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected extension point from 
                the model.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.extension_point_property_fields">

          <title>Property Fields For Extension Point</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Extension Point 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Extension Point</secondary></indexterm>
                <para>Text box. The name of the extension point.</para>

                <tip>

                  <para>It is quite common to leave extension points 
                  unnamed in use case analysis, since they are always 
                  listed (within use cases and extend relationships) by 
                  their location.</para>

                </tip>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for extension points.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Location</literal></term>

              <listitem>

                <indexterm><primary>Extension Point 
                Location</primary></indexterm>
                <indexterm><primary>Location</primary><secondary>of 
                Extension Point</secondary></indexterm>
                <para>Text box. A description of the location of this 
                extension point within the owning use case.</para>

                <tip>

                  <para>Extension points are always listed (within use 
                  cases and extend relationships) by their location. 
                  Typically this will be the number/name of the 
                  paragraph in the specification.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base Use Case</literal></term>

              <listitem>

                <indexterm><primary>Extension Point Base Use 
                Case</primary></indexterm>
                <indexterm><primary>Base Use 
                Case</primary><secondary>of Extension 
                Point</secondary></indexterm>
                <para>Text box. Shows the base use case within which 
                this extension point is defined. Button&nbsp;1 Double Click 
                will navigate to the use case.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Extend</literal></term>

              <listitem>

                <indexterm><primary>Extension Point Extending Use 
                Cases</primary></indexterm>
                <indexterm><primary>Extending Use 
                Cases</primary><secondary>of Extension 
                Point</secondary></indexterm>
                <para>Text box. Lists all use cases which extend the 
                base use case through this extension point.</para>

                <para>Where an extending use case exists, button&nbsp;1 
                double click will navigate to that relationship.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.association_use_case">

        <title>Association</title>

        <para>An association on a use case diagram represents a 
        relationship between an actor and a use case showing that 
        actor&apos;s involvement in the use case. The invocation of the 
        use case will involve some (significant) change perceived by 
        the actor.</para>

        <para>Associations are described fully under class diagrams 
        (see <xref linkend="s1.ref.association_class"/>).</para>

      </sect1>

      <sect1 id="s1.ref.association_end_use_case">

        <title>Association End</title>

        <para>Association ends are described under class diagrams (see 
        <xref linkend="s1.ref.association_end_class"/>).</para>

      </sect1>

      <sect1 id="s1.ref.dependency_use_case">

        <title>Dependency</title>

        <para>Dependencies are described under class diagrams (see 
        <xref linkend="s1.ref.dependency_class"/>).</para>

        <caution>

          <para>Dependency has little use in use case diagrams. It is 
          provided, because earlier versions of ArgoUML used it 
          (incorrectly) to implement include and extends 
          relationships.</para>

        </caution>

      </sect1>

      <sect1 id="s1.ref.generalization_use_case">

        <title>Generalization</title>

        <indexterm><primary>Generalization</primary></indexterm>
        <para>Generalization is a relationship between two use cases or 
        two actors. Where A is a generalization of B, it means A 
        describes more general behavior and B a more specific version 
        of that behavior.</para>

        <para>Examples for a travel agent sales system might be the use 
        case for making a booking as a generalization of the use case 
        for making a flight booking and a salesman actor being a 
        generalization of a supervisor actor (since supervisors can 
        also act as salesmen, but not vice versa).</para>

        <para>Generalization is analogous to class inheritance within 
        OO programming.</para>

        <note>

          <para>It is easy to confuse <emphasis>extends</emphasis> 
          relationships between use cases with generalization. However 
          extends is about augmenting a use case&apos;s behavior at a 
          specific point. Generalization is about specializing the 
          behavior throughout the use case.</para>

        </note>

        <para>Within the UML metamodel, <literal>
        Generalization</literal> is a sub-class of <literal>
        Relationship</literal>.</para>

        <para>Generalization is represented as an arrow with white 
        filled head from the specialized use case or actor to the 
        generalized use case or actor (see 
        <xref linkend="fig.ref.use_case_diagram"/>).</para>

        <sect2>

          <title>Generalization Details Tabs</title>

          <indexterm><primary>Generalization Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Generalization</secondary></indexterm>
          <para>The details tabs that are active for associations are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.generalization_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.generalization_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>The values in the "bounds" field 
                    of the generalization are not editable, 
                    since they are determined by 
                    the properties of the endpoints of the line.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Generalization</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    generalization is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>Derived generalizations still have their 
                      value in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.generalization_property_toolbar">

          <title>Generalization Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model. For a generalization this will be the package 
                containing the generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                generalization, navigating immediately to the 
                properties tab for that generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected generalization from the 
                model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a generalization from the diagram, but keep it within 
                  the model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.generalization_property_fields">

          <title>Property Fields For Generalization</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Text box. The name of the generalization.</para>

                <tip>

                  <para>It is quite common to leave generalizations 
                  unnamed in use case analysis.</para>

                </tip>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for associations.</para>

                </note>

                <note>

                  <para>There is no representation of the name of a 
                  generalization on the diagram.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Discriminator</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Discriminator</primary></indexterm>
                <indexterm>
                <primary>Discriminator</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Text box. The name of a discriminator for the 
                specialization. UML&nbsp;1.4 allows grouping of 
                specializations into a number of sets, on the basis of 
                this value.</para>

                <tip>

                  <para>The empty string <quote /> is a valid entry 
                  (and the default) for this field. The discriminator 
                  is only of practical use in cases of multiple 
                  inheritance. A (class diagram) example is shown in 
                  <xref linkend="fig.discriminator_example"/>. Here 
                  each type of user should inherit from two sorts of 
                  user. One distinguishing between local or remote user 
                  (which can be identified by one discriminator) and 
                  one indicating their function as a user (identified 
                  by a different discriminator).</para>

                  <para>There is little point in using this within a 
                  use case diagram.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Text box with navigation button. 
                Records the namespace for the 
                generalization. This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Parent</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Parent</primary></indexterm>
                <indexterm><primary>Parent</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Text box. Shows the use case or actor that is the 
                <emphasis>parent</emphasis> in this relationship, i.e. 
                the more general end of the relationship. Button&nbsp;1 
                Double Click on this entry will navigate to that use 
                case or actor. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Child</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Child</primary></indexterm>
                <indexterm><primary>Child</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Text box. Shows the use case or actor that is the 
                <emphasis>child</emphasis> in this relationship, i.e. 
                the more specific end of the relationship. Button&nbsp;1 
                Double Click on this entry will navigate to that use 
                case or actor. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Powertype</literal></term>

              <listitem>

                <indexterm><primary>Generalization 
                Powertype</primary></indexterm>
                <indexterm><primary>Powertype</primary><secondary>of 
                Generalization</secondary></indexterm>
                <para>Drop down selector providing access to all 
                standard UML types provided by ArgoUML and all new 
                classes created within the current model.</para>

                <para>This is the type of the child entity of the 
                generalization.</para>

                <tip>

                  <para>This can be ignored for use case analysis. The 
                  only sensible value to put in would be the child use 
                  case type (as a classifier, this appears in the drop 
                  down list.</para>

                </tip>

              </listitem>

            </varlistentry>

          </variablelist>

          <figure float="1" id="fig.discriminator_example">

            <title>Example use of a discriminator with 
            generalization</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/discriminator_example.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.extend">

        <title>Extend</title>

        <indexterm><primary>Extend Relationship</primary></indexterm>
        <para>Extend is a relationship between two use cases. Where A 
        extends B, it means A describes some additional behavior 
        that is executed conditionally (under exceptional circumstances)
        at some point
        during the normal behavior of B.
        </para>

        <para>In some respects extend is like generalization. However 
        the key difference is that the extended use case defines 
        <emphasis>extension points</emphasis> (see 
        <xref linkend="s1.ref.extension_point"/>), which are the only 
        places where its behavior may be extended. The extending use 
        case must define at which of these extension points it adds 
        behavior.</para>

        <para>This makes the use of extend more tightly controlled than 
        general extension, and it is thus preferred wherever 
        possible.</para>

        <para>Examples for a travel agent sales system might be the use 
        case for paying for a ticket, which has an extension point in 
        the specification of the payment. Extending use cases may then 
        extend at this point to pay by cash, credit card etc.</para>

        <para>Within the UML metamodel, <literal>Extend</literal> is a 
        sub-class of <literal>Relationship</literal>.</para>

        <para>An extend relationship is represented as a dotted link 
        with an open arrow head and a label <literal>
        &laquo;extend&raquo;</literal>. If a condition is defined, it is shown 
        under the <literal>&laquo;extend&raquo;</literal> label (see 
        <xref linkend="fig.ref.use_case_diagram"/>).</para>

        <sect2>

          <title>Extend Details Tabs</title>

          <indexterm><primary>Extend Relationship Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Extend Relationship</secondary></indexterm>
          <para>The details tabs that are active for extend 
          relationships are as follows.</para>

          <note>

            <para>There is no source tab, since there is no source code 
            that could be generated for an extend relationship.</para>

          </note>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.extend_property_toolbar"/> and 
                <xref linkend="s2.ref.extend_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab</para>

                <note>

                  <para>
                    The values in the "bounds" field of the extend
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Extend</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the extend 
                    relationship is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>Derived extend relationships could have 
                      their value in analysis to introduce useful names 
                      or concepts.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.extend_property_toolbar">

          <title>Extend Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model. For a extend this will be the package containing 
                the extend.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/extension_point.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New extension point</literal></term>

              <listitem>

                <indexterm><primary>Add Extend 
                Relationship</primary></indexterm>
                <indexterm><primary>New Extend 
                Relationship</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Extend 
                Relationship</secondary></indexterm>
                <para>This creates a new use case extension point 
                within the namespace of the current extend 
                relationship, with the current extend relationship as 
                its first extending relationship.</para>

                <tip>

                  <para>While it is perfectly valid to create extension 
                  points from an extend relationship, the created 
                  extension point will have no associated use case (it 
                  can subsequently be set up).</para>

                  <para>It would be more usual to instead create the 
                  extension point within a use case and subsequently 
                  link to it from an extend relationship (see 
                  <xref linkend="s2.ref.extend_property_fields"/> 
                  below).</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                extent relationship, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected extend relationship 
                from the model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a extend from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.extend_property_fields">

          <title>Property Fields For Extend</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Extend Relationship 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of Extend 
                Relationship</secondary></indexterm>
                <para>Text box. The name of the extend 
                relationship.</para>

                <tip>

                  <para>It is quite common to leave extends unnamed in 
                  use case analysis.</para>

                </tip>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for extend relationships.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Extend Relationship 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Extend Relationship</secondary></indexterm>
                <para>Text box. Records the namespace for the extend 
                relationship. This is the package hierarchy.</para>

                <para>Button&nbsp;1 Double Click on the entry will navigate 
                to the package defining this namespace (or the model 
                for the top level namespace).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base Use Case</literal></term>

              <listitem>

                <indexterm><primary>Extend Relationship Base Use 
                Case</primary></indexterm>
                <indexterm><primary>Base Use 
                Case</primary><secondary>of Extend 
                Relationship</secondary></indexterm>
                <para>Text box. Shows the use case that is 
                being extended by this extend relationship. Button&nbsp;1 
                double
                click on this entry will navigate 
                to the base use case.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Extension</literal></term>

              <listitem>

                <indexterm><primary>Extend Relationship 
                Extension</primary></indexterm>
                <indexterm><primary>Extension</primary><secondary>of 
                Extend Relationship</secondary></indexterm>
                <para>Text box. Show the use case that is 
                doing the extending through this extend relationship. 
                Button&nbsp;1 double click on this entry 
                will navigate 
                to the extension use case.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Extension Points</literal></term>

              <listitem>

                <indexterm><primary>Extend Relationship Extension 
                Point</primary></indexterm>
                <indexterm><primary>Extension 
                Point</primary><secondary>of Extend 
                Relationship</secondary></indexterm>
                <para>Text box. Lists the extension points 
                of the base use case where the extension 
                will be applied if the condition holds.
                </para>

                <note>

                  <para>If the condition
                  is fulfilled, the sequence obeyed by the use-case instance 
                  is extended to include the sequence of the extending use case.
                  The different parts of the extending use case are inserted 
                  at the locations defined by the sequence of extension points 
                  in the relationship -- one part at each referenced 
                  extension point. 
                  Note that the condition is only evaluated once: 
                  at the first referenced extension point, 
                  and if it is fulfilled all of the extending use case 
                  is inserted in the original sequence.</para>
                  <para>Hence, the sequence of the extension points is 
                  irrelevant, except for the position of the first one; 
                  since that one determines 
                  where the condition is evaluated.
                  </para>

                </note>

                <para>Where an extension point has been created, 
                button&nbsp;1 double click will navigate to that 
                relationship. Button&nbsp;2 gives a pop up menu with
                the following
                entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. The <quote>Ad/Remove 
                    ExtensionPoints</quote> window opens. In this 
                    window it is possible to build a list of extension 
                    points.</para>

                  </listitem>

                  <listitem>

                    <para><literal>New</literal>. Add a new extension 
                    point in the list and navigate to it. The current 
                    extend relationship is added as the first in list 
                    of extending relationships of the new extension 
                    point.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more extension points listed, and 
                    the extension point selected is not at the top. It moves 
                    the extension point up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more extension points listed, and 
                    the extension point selected is not at the bottom. It 
                    moves the extension point down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Condition</literal></term>

              <listitem>

                <para>Text area. Multi-line textual description of any 
                condition attached to the extend relationship.</para>
                <para>The text entered here is shown on the diagram.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.include">

        <title>Include</title>

        <indexterm><primary>Include Relationship</primary></indexterm>
        <para>Include is a relationship between two use cases. Where A 
        includes B, it means B described behavior that is to be 
        included in the description of the behavior of A at some point 
        (defined internally by A).</para>

        <para>Examples for a travel agent sales system might be the use 
        case for booking travel, which includes use cases for booking 
        flights and taking payment.</para>

        <para>Within the UML metamodel, <literal>Include</literal> is a 
        sub-class of <literal>Relationship</literal>.</para>

        <para>An include relationship is represented as a dotted link 
        with an open arrow head and a label <literal>
        &laquo;include&raquo;</literal> (see 
        <xref linkend="fig.ref.use_case_diagram"/>).</para>

        <sect2>

          <title>Include Details Tabs</title>

          <indexterm><primary>Include Relationship Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Include Relationship</secondary></indexterm>
          <para>The details tabs that are active for include 
          relationships are as follows.</para>

          <note>

            <para>There is no source tab, since there is no source code 
            that could be generated for an include relationship.</para>

          </note>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.include_property_toolbar"/> and 
                <xref linkend="s2.ref.include_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab</para>

                <note>

                  <para>
                    The values in the "bounds" field of the 
                    include relationships
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Include</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the include 
                    relationship is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>Derived include relationships could have 
                      their value in analysis to introduce useful names 
                      or concepts.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.include_property_toolbar">

          <title>Include Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model. For a include this will be the package 
                containing the include.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                include relationship, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected include relationship 
                from the model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a include from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.include_property_fields">

          <title>Property Fields For Include</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Include Relationship 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of Include 
                Relationship</secondary></indexterm>
                <para>Text box. The name of the include 
                relationship.</para>

                <tip>

                  <para>It is quite common to leave include 
                  relationships unnamed in use case analysis.</para>

                </tip>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for include relationships.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Include Relationship 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Include Relationship</secondary></indexterm>
                <para>Text box. Records the namespace for the include. 
                This is the package hierarchy.</para>

                <para>Button&nbsp;1 click on the entry will navigate to the 
                package defining this namespace (or the model for the 
                top level namespace).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base Use Case</literal></term>

              <listitem>

                <indexterm><primary>Include Relationship 
                Base</primary></indexterm>
                <indexterm><primary>Base</primary><secondary>of Include 
                Relationship</secondary></indexterm>
                <para>Drop down selector. Records the use case that is 
                doing the including in this include relationship. 
                Button&nbsp;1 click on this entry will give a drop down menu 
                of all available use cases which may be selected by 
                button&nbsp;1 click.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Included Use Case</literal></term>

              <listitem>

                <indexterm><primary>Include Relationship Included Use 
                Case</primary></indexterm>
                <indexterm><primary>Included Use 
                Case</primary><secondary>of Include 
                Relationship</secondary></indexterm>
                <para>Drop down selector. Records the use case that is 
                being included by this include relationship. Button&nbsp;1 
                click on this entry will give a drop down menu of all 
                available use cases (and an empty entry) which may be 
                selected by button&nbsp;1 click.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entclass">

      <title>Class Diagram Model Element Reference</title>

      <indexterm><primary>Class Diagram</primary></indexterm>
      <indexterm><primary>Object Diagrams</primary></indexterm>
      <indexterm><primary>Package Diagrams</primary></indexterm>
      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a class diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>Class diagrams are used for only one of the UML static 
        structure diagrams, the class diagram itself. Object diagrams 
        are represented on the ArgoUML deployment diagram.</para>

        <para>In addition, ArgoUML uses the class diagram to show model 
        structure through the use of packages.</para>

        <para>There is a close relationship between this material and 
        the Properties Tab of the Details Pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        Properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <para><xref linkend="fig.ref.class_diagram"/> shows a class 
        diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.class_diagram">

          <title>Possible model elements on a class diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/class_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <para><xref linkend="fig.ref.package_diagram"/> shows a package 
        diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.package_diagram">

          <title>Possible model elements on a package diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/package_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <para><xref linkend="fig.ref.datatype_diagram"/> shows a 
        datatype 
        diagram with a datatype and an enumeration displayed.</para>

        <figure float="1" id="fig.ref.datatype_diagram">

          <title>Possible model elements on a datatype diagram.</title>
          <!-- See ClassDiagram-Datatypes.zargo -->

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/classdiagram-datatypes.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <para><xref linkend="fig.ref.stereotype_diagram"/> shows a 
        stereotype definition
        diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.stereotype_diagram">

          <title>Possible model elements on a 
          stereotype definition diagram.</title>
          <!-- See ClassDiagram-Datatypes.zargo -->

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/classdiagram-stereotype-definition.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>Limitations Concerning Class Diagrams in 
          ArgoUML</title>

          <para>Various limitations exist in V0.26 of ArgoUML 
          for stereotype definition diagrams. 
          E.g. the implementation does not allow 
          stereotype compartments
          to be shown on stereotype definition diagrams.</para>

          <para>Another variant of the class diagram within the UML standard 
          is the <emphasis>object diagram</emphasis>. There is 
          currently no support for objects or links within ArgoUML 
          class diagrams. Instead the ArgoUML deployment diagram does 
          have both objects and links, and can be used to draw object 
          diagrams.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.package">

        <title>Package</title>

        <indexterm><primary>Package</primary></indexterm>
        <para>The package is the main organizational model element within 
        ArgoUML. In the UML metamodel it is a sub-class of both 
        <literal>Namespace</literal> and <literal>
        GeneralizableElement</literal>.</para>

        <note>

          <para>ArgoUML also implements the UML <literal>
          Model</literal> model element as a sub-class of package, but 
          <emphasis>not</emphasis> the <literal>Subsystem</literal> 
          model element.</para>

        </note>

        <para>ArgoUML also implements some less common aspects of UML 
        model management. In particular the relationship UML 1.4 
        defines as <literal>Generalization</literal> and the sub-class 
        dependency <literal>Permission</literal> for use between 
        packages.</para>

        <sect2>

          <title>Package Details Tabs</title>

          <indexterm><primary>Package Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Package</secondary></indexterm>
          <para>The details tabs that are active for packages are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.package_property_toolbar"/> and 
                <xref linkend="s2.ref.package_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The editable <literal>Bounds</literal> 
                field defines the bounding box for the package on the 
                diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Package</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the package 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived packages still have their value in 
                      analysis to introduce useful names or concepts, 
                      and in design to avoid re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.package_property_toolbar">

          <title>Package Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/package.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Package</literal></term>

              <listitem>

                <para>This creates a new package within the package 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that package.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Datatype</literal></term>

              <listitem>

                <indexterm><primary>Add Datatype</primary></indexterm>
                <indexterm><primary>New Datatype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Datatype</secondary></indexterm>
                <para>This creates a new Datatype (see 
                <xref linkend="s1.ref.datatype"/>) for the selected 
                package, navigating immediately to the properties tab 
                for that datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Enumeration</literal></term>

              <listitem>

                <indexterm><primary>Add Enumeration</primary></indexterm>
                <indexterm><primary>New Enumeration</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Enumeration</secondary></indexterm>
                <para>This creates a new Enumeration (see 
                <xref linkend="s1.ref.enumeration"/>) for the selected 
                package, navigating immediately to the properties tab 
                for that enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                package, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/tag_definition.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Tag Definition</literal></term>

              <listitem>

                <para>This creates a new tag definition (see 
                <xref linkend="s1.ref.tagdefinition"/>) within the 
                package 
                (which appears on no diagram), navigating immediately 
                to the properties tab for that tagdefinition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete Package</literal></term>

              <listitem>

                <para>Deletes the package from the model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a package from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.package_property_fields">

          <title>Property Fields For Package</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Package Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Text box. The name of the package. The name of a 
                package, like all packages, is by convention all lower 
                case, not containing any punctuation marks.</para>

                <note>

                  <para>By default a new package has no name defined. 
                  The package will appear with the name <literal>(Unnamed 
                  Package)</literal> in the explorer.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Package 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Drop down selector. Records the namespace for the 
                package. This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <para>Radio box, with four entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal>, and
                <literal>package</literal>. Indicates whether the 
                package is visible outside the package.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Package 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Check box, with entries <literal>
                abstract</literal>, <literal>leaf</literal> and 
                <literal>root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this package cannot be instantiated, 
                    but must always be specialized.</para>

                    <tip>

                      <para>The meaning of <literal>abstract</literal> 
                      applied to a package if not that clear. It might 
                      mean that the package contains interfaces or 
                      abstract classes without realizations. This is 
                      probably better handled through stereotyping of 
                      the package (for example <literal>
                      &laquo;facade&raquo;</literal>).</para>

                    </tip>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    package can have no further subpackages.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Root</literal> indicates that it is 
                    the top level package.</para>

                    <tip>

                      <para>Within ArgoUML <literal>Root</literal> only 
                      meaningfully applies to the Model, since all 
                      packages sit within the model. This could be used 
                      to emphasize that the Model is at the top 
                      level.</para>

                    </tip>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <indexterm><primary>Package 
                Generalizations</primary></indexterm>
                <indexterm>
                <primary>Generalizations</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Text area. Lists any package that 
                <emphasis>generalizes</emphasis> this package.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <indexterm><primary>Package 
                Specializations</primary></indexterm>
                <indexterm>
                <primary>Specializations</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Text box. Lists any specialized package (i.e. for 
                which this package is a generalization.</para>

                <para>button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owned Elements</literal></term>

              <listitem>

                <indexterm><primary>Package Owned 
                Elements</primary></indexterm>
                <indexterm><primary>Owned 
                Elements</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Text area. A listing of all the packages, 
                classes, interfaces, datatypes, actors, use cases, 
                associations, generalizations, stereotypes, etc. within 
                the package.</para>

                <para>Button&nbsp;1 double click on any item listed here 
                navigates to that model element.</para>

              </listitem>

            </varlistentry>
            
            <varlistentry>
            
              <term><literal>Imported Elements</literal></term>
              
              <listitem>
                <indexterm><primary>Package Imported 
                Elements</primary></indexterm>
                <indexterm><primary>Imported 
                Elements</primary><secondary>of 
                Package</secondary></indexterm>
                <para>Text Area. A listing of all imported elements,
                i.e. elements that are owned by a different package, but 
                are explicitely made visible in this package.</para>
                
                <para>Button&nbsp;1 double click on any item listed here 
                navigates to that model element.
                Button&nbsp;2 gives a pop up menu with
                the following entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. The <quote>Add/Remove 
                    Imported Elements</quote> window opens. In this 
                    window it is possible to build a list of imported 
                    elements.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Remove</literal>.  
                    Removes the import.</para>

                  </listitem>

                </itemizedlist>

              </listitem>
              
            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.datatype_class">

        <title>Datatype</title>

        <para>Datatypes are not specific to packages or class diagrams, 
        and are discussed within the chapter on top level model elements 
        (see <xref linkend="s1.ref.datatype"/>).</para>

      </sect1>

      <sect1 id="s1.ref.enumeration_class">

        <title>Enumeration</title>

        <para>Enumeration are not specific to packages or class diagrams, 
        and are discussed within the chapter on top level model elements 
        (see <xref linkend="s1.ref.enumeration"/>).</para>

      </sect1>

      <sect1 id="s1.ref.stereotype_class">

        <title>Stereotype</title>

        <para>Stereotypes are not specific to packages or class 
        diagrams, and are discussed within the chapter on top level 
        model elements (see <xref linkend="s1.ref.stereotype"/>).</para>

      </sect1>

      <sect1 id="s1.ref.class_class">

        <title>Class</title>

        <indexterm><primary>Class</primary></indexterm>
        <para>The class is the dominant model element on a class diagram. In 
        the UML metamodel it is a sub-class of <literal>
        Classifier</literal> and <literal>
        GeneralizableElement</literal>.</para>

        <para>A class is represented on a class diagram as a rectangle 
        with three compartments. The top compartment 
        displays the class name (and stereotypes), the second 
        compartment any attributes and the third any operations. These 
        last two compartments may optionally be hidden.</para>

        <sect2>

          <title>Class Details Tabs</title>

          <indexterm><primary>Class Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Class</secondary></indexterm>
          <para>The details tabs that are active for classes are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.class_property_toolbar"/> and 
                <xref linkend="s2.ref.class_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The tick boxes, <literal>
                Attributes</literal> and <literal>Operations</literal> 
                allow the attributes and operations compartments to be 
                shown (the default) or hidden. This is a setting valid 
                for only the current diagram that shows the class. The 
                editable
                <literal>Bounds</literal> field defines the bounding 
                box for the package on the diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This contains a template for the 
                class declaration and declarations of associated 
                classes.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Constraints</literal></term>

              <listitem>

                <para>Standard tab. There are no standard constraints 
                defined for <literal>Class</literal> within the UML 
                metamodel.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotypes</literal></term>

              <listitem>

                <para>Standard tab. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Class Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Class</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Class</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    class.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the class 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived classes still have their value in 
                      analysis to introduce useful names or concepts, 
                      and in design to avoid re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Classifier.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.class_property_toolbar">

          <title>Class Property Toolbar</title>

          <indexterm><primary>Class Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Class</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New attribute</literal></term>

              <listitem>

                <para>This creates a new attribute (see 
                <xref linkend="s1.ref.attribute"/>) within the class, 
                navigating immediately to the properties tab for that 
                attribute.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New operation</literal></term>

              <listitem>

                <para>This creates a new operation (see 
                <xref linkend="s1.ref.operation"/>) within the class, 
                navigating immediately to the properties tab for that 
                operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New reception</literal></term>

              <listitem>

                <para>This creates a new reception, navigating 
                immediately to the properties tab for that 
                reception.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/inner_class.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New inner class</literal></term>

              <listitem>

                <para>This creates a new inner class (which appears on 
                no diagram) within the class. This belongs to the class 
                and is restricted to the namespace of the class. It 
                exactly models the Java concept of inner class. As an 
                inner class it needs no attributes or operations, since 
                it shares those of its owner.</para>

                <note>

                  <para>Inner class is not a separate concept in UML. 
                  This is a convenient shorthand for creating a class 
                  that is restricted to the namespace of its owning 
                  class.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center" fileref="images/icons/class.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New class</literal></term>

              <listitem>

                <para>This creates a new class (which appears on no 
                diagram) within the same namespace as the current 
                class.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                class, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the class from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a class from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.class_property_fields">

          <title>Property Fields For Class</title>

          <indexterm><primary>Class Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Class</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Class Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Class</secondary></indexterm>
                <para>Text box. The name of the class. The name of a 
                class has a leading capital letter, with words 
                separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>The ArgoUML critics will complain about class 
                  names that do not have an initial capital.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector with navigation button. 
                Records and allows setting of 
                the namespace for the class. This is the package 
                hierarchy.</para>

                <para>Button&nbsp;1 click on the entry will move the class 
                to the selected namespace.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Class 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Class</secondary></indexterm>
                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal>, <literal>
                Root</literal>, and <literal>Active</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this class cannot be instantiated, but 
                    must always be subclassed. The name of an abstract 
                    class is displayed in italics on the diagram.</para>

                    <caution>

                      <para>If a class has any abstract operations, 
                      then it should be declared abstract. ArgoUML will 
                      not enforce this.</para>

                    </caution>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    class cannot be further subclassed, while <literal>
                    Root</literal> indicates it can have no superclass. 
                    It is possible for a class to be both Abstract and 
                    Leaf, since its static operations may still be 
                    referenced.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Active</literal> indicates that this 
                    class exhibits dynamic behavior (and is thus 
                    associated with a state or activity diagram).</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <para>Radio box, with four entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal>, and
                <literal>package</literal>. Indicates whether the 
                class is visible outside the namespace.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Client Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists the <quote>depending</quote> 
                ends of the relationship, i.e. the end that makes use 
                of the other end.</para>

                <para>Button&nbsp;1 double click navigates to the dependency 
                and opens its property tab.</para>
                <para>Button&nbsp;2 click shows a pop-up menu with one entry
                <literal>Add...</literal> that
                opens a dialog box where you can add and remove 
                depending modelelements.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Supplier Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists the <quote>supplying</quote> 
                ends of the relationship, i.e. the end supplying what 
                is needed by the other end.</para>

                <para>Button&nbsp;1 double click navigates to the dependency 
                and opens its property tab.</para>
                <para>Button&nbsp;2 click shows a pop-up menu with one entry
                <literal>Add...</literal> that
                opens a dialog box where you can add and remove 
                dependent modelelements.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any class that 
                <emphasis>generalizes</emphasis> this class.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized class (i.e. for 
                which this class is a generalization).</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Attributes</literal></term>

              <listitem>

                <para>Text area. Lists all the attributes (see 
                <xref linkend="s1.ref.attribute"/>) defined for this 
                class. Button&nbsp;1 double click navigates to the selected 
                attribute. Button&nbsp;2 gives a pop up menu with two 
                entries, which allow reordering the attributes.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more attributes listed, and 
                    the attribute selected is not at the top. It moves 
                    the attribute up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more attributes listed, and 
                    the attribute selected is not at the bottom. It 
                    moves the attribute down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association Ends</literal></term>

              <listitem>

                <para>Text box. Lists any association ends (see 
                <xref linkend="s1.ref.association_class"/>) of 
                associations connected to this class.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Text area. Lists all the operations (see 
                <xref linkend="s1.ref.operation"/>) defined on this 
                class. Button&nbsp;1 click navigates to the selected 
                operation. Button&nbsp;2 gives a pop up menu with two 
                entries, which allow reordering the operations.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the top. It moves 
                    the operation up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more operations listed, and 
                    the operation selected is not at the bottom. It 
                    moves the operation down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owned Elements</literal></term>

              <listitem>

                <para>Text area. A listing of model elements contained 
                within the classes&apos; namespace. This is where any 
                inner class (see 
                <xref linkend="s2.ref.class_property_toolbar"/>) will 
                appear</para>

                <para>Button&nbsp;1 double click on any of the model elements 
                navigates to that model element.</para>

                <tip>

                  <para>Most namespace hierarchies should be managed 
                  through the package mechanism. Namespace hierarchies 
                  through classes are best restricted to inner classes. 
                  Conceivable datatypes, signals and interfaces could 
                  also appear here, but actors and use cases would seem 
                  of no value.</para>

                </tip>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.attribute">

        <title>Attribute</title>

        <indexterm><primary>Attribute</primary></indexterm>
        <para>Attribute is a named slot within a class (or other 
        <literal>Classifier</literal>) describing a range of values 
        that may be held by instances of the class. In the UML 
        metamodel it is a sub-class of <literal>
        StructuralFeature</literal> which is itself a sub-class of 
        <literal>Feature</literal>.</para>

        <para>An attribute is represented in the diagram on a single 
        line within the attribute compartment of the class. Its syntax 
        is as follows:</para>

        <blockquote>

          <para><emphasis>visibility</emphasis> 
          <emphasis>attributeName</emphasis> <literal>:</literal> 
          <emphasis>type</emphasis> [<literal>=</literal> 
          <emphasis>initialValue</emphasis>]</para>

        </blockquote>

        <para><emphasis>visibility</emphasis> is <literal>+</literal>, 
        <literal>#</literal>, <literal>-</literal> or 
        <literal>~</literal> corresponding to 
        <literal>public</literal>, <literal>protected</literal>, 
        <literal>private</literal>, or <literal>package</literal> 
        visibility respectively.</para>

        <para><emphasis>attributeName</emphasis> is the actual name of 
        the attribute being declared.</para>

        <para><emphasis>type</emphasis> is the type (UML datatype, 
        class or interface) declared for the attribute.</para>

        <para><emphasis>initialValue</emphasis> is any initial value to 
        be given to the attribute when an instance of the class is 
        created. This may be overridden by any constructor 
        operation.</para>

        <para>In addition any attribute declared static will have its 
        whole entry underlined on the diagram.</para>

        <sect2 id="s2.ref.attribute_details_tabs">

          <title>Attribute Details Tabs</title>

          <indexterm><primary>Attribute Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Attribute</secondary></indexterm>
          <para>The details tabs that are active for attributes are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.attribute_property_toolbar"/> and 
                <xref linkend="s2.ref.attribute_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Constraints</literal></term>

              <listitem>

                <para>Standard tab. There are no standard constraints 
                defined for <literal>Attribute</literal> within the UML 
                metamodel.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Attribute Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Attribute</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>transient</literal>.</para>

                  </listitem>

                  <listitem>

                    <para><literal>volatile</literal>. This is an 
                    ArgoUML extension to the UML 1.4 standard to 
                    indicate that this attribute is realized in some 
                    volatile form (for example it will be a memory 
                    mapped control register).</para>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Attribute.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.attribute_property_toolbar">

          <title>Attribute Property Toolbar</title>

          <indexterm><primary>Attribute Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Attribute</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up_previous.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go to Previous</literal></term>

              <listitem>

                <para>Navigate to the previous attribute 
                of the class that owns them. 
                This button is downlighted 
                if the current attribute is the first one.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up_next.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go to Next</literal></term>

              <listitem>

                <para>Navigate to the next attribute 
                of the class that owns them. 
                This button is downlighted 
                if the current attribute is the last one.</para>

              </listitem>

            </varlistentry>


            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New attribute</literal></term>

              <listitem>

                <para>This creates a new attribute within the owning 
                class of the current attribute, navigating immediately 
                to the properties tab for that attribute.</para>

                <tip>

                  <para>This is a very convenient way to add a number 
                  of attributes, one after the other, to a class.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Datatype</literal></term>

              <listitem>

                <indexterm><primary>Add Datatype</primary></indexterm>
                <indexterm><primary>New Datatype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Datatype</secondary></indexterm>
                <para>This creates a new Datatype (see 
                <xref linkend="s1.ref.datatype"/>) for the selected 
                attribute, navigating immediately to the properties tab 
                for that datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/enumeration.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Enumeration</literal></term>

              <listitem>

                <indexterm><primary>Add Enumeration</primary></indexterm>
                <indexterm><primary>New Enumeration</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Enumeration</secondary></indexterm>
                <para>This creates a new Enumeration (see 
                <xref linkend="s1.ref.enumeration"/>) for the  
                package that owns the class,
                navigating immediately to the properties tab 
                for that enumeration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                attribute, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the attribute from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. If desired 
                  the whole attribute compartment can be hidden on the 
                  diagram using the <emphasis>style</emphasis> tab (see 
                  <xref linkend="s2.ref.attribute_property_toolbar"/>) 
                  or the button&nbsp;2 pop up menu for the class on the 
                  diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.attribute_property_fields">

          <title>Property Fields For Attribute</title>

          <indexterm><primary>Attribute Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Attribute</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Attribute Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Text box. The name of the attribute. The name of 
                a attribute has a leading lower case letter, with words 
                separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>The ArgoUML critics will complain about 
                  attribute names that do not have an initial lower 
                  case letter.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owner</literal></term>

              <listitem>

                <para>Text box. Records the class which contains this 
                attribute.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the class.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Multiplicity</literal></term>

              <listitem>

                <indexterm><primary>Attribute 
                Multiplicity</primary></indexterm>
                <indexterm><primary>Multiplicity</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Editable drop down selector with checkmark. 
                The default value 
                (1) is that there is one instance of this attribute for 
                each instance of the class, i.e. it is a scalar. The 
                drop down provides a number of commonly used 
                specifications for non-scalar attributes.</para>
                <para>When the checkmark is unchecked, 
                then the multiplicity remains undefind in the model
                (and the drop down selector is downlighted).</para>

                <note>

                  <para>ArgoUML presents a number of predefined ranges 
                  for multiplicity for easy access. The user may also 
                  enter any user defined range that follows the UML 
                  syntax, such as <quote>1..3,7,10</quote>.</para>

                  <para>The value <literal>1..1</literal> is equivalent 
                  to the default (exactly one scalar instance). The 
                  selection <literal>0..1</literal> indicates an 
                  optional scalar attribute.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Attribute 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>, 
                <literal>protected</literal> and 
                <literal>package</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>public</literal>. The attribute is 
                    available to any model element that can see the owning 
                    class.</para>

                  </listitem>

                  <listitem>

                    <para><literal>private</literal>. The attribute is 
                    available only to the owning class (and any inner 
                    classes).</para>

                  </listitem>

                  <listitem>

                    <para><literal>protected</literal>. The attribute 
                    is available only to the owning class, or model elements 
                    that are subclasses of the owning class.</para>

                  </listitem>


                  <listitem>

                    <para><literal>package</literal>. The attribute 
                    is available only to model elements contained in the
                    same package.</para>

                  </listitem>
                  
                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Changeability</literal></term>

              <listitem>

                <indexterm><primary>Attribute 
                Changeability</primary></indexterm>
                <indexterm>
                <primary>Changeability</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Radio box, with entries <literal>
                addOnly</literal>, <literal>changeable</literal>, and 
                <literal>frozen</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>addOnly</literal>. Meaningful only 
                    if the multiplicity is not fixed to a single value. 
                    Additional values may be added to the set of 
                    values, but once created a value may not be removed 
                    or altered.</para>

                  </listitem>

                  <listitem>

                    <para><literal>changeable</literal>. There are no 
                    restrictions of modification.</para>

                  </listitem>

                  <listitem>

                    <para><literal>frozen</literal>. Also named 
                    <quote>immutable</quote>. The value of the 
                    attribute may not change during the lifetime of the 
                    owner class. The value must be set at object 
                    creation, and may never change after that. This 
                    implies that there is usually an argument for this 
                    value in a constructor and that there is no 
                    operation that updates this value.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <para>Check box for <literal>static</literal>. If 
                unchecked (the defaults) then the attribute has 
                <quote>instance scope</quote>. If checked, then the 
                attribute is static, i.e. it has <quote>class 
                scope</quote>. Static attributes are indicated on the 
                diagram by underlining.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Type</literal></term>

              <listitem>

                <indexterm><primary>Attribute Type</primary></indexterm>
                <indexterm><primary>Type</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Drop down selector with navigation button. 
                The type of this attribute. 
                This can be any UML <literal>Classifier</literal>, 
                although in practice only <literal>Class</literal>, 
                <literal>DataType</literal>, or <literal>
                Interface</literal> make any sense.</para>
                
                <para>Pressing the navigation button
                will navigate to the property panel for the 
                currently selected type. (see 
                <xref linkend="s1.ref.class_class"/>, 
                <xref linkend="s1.ref.datatype_class"/> and 
                <xref linkend="s1.ref.interface_class"/>).</para>

                <note>

                  <para>A type must be declared (it can be <literal>
                  void</literal>). By default ArgoUML supplies <literal>
                  int</literal> as the type.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Initial Value</literal></term>

              <listitem>

                <indexterm><primary>Attribute Initial 
                Value</primary></indexterm>
                <indexterm><primary>Initial 
                Value</primary><secondary>of 
                Attribute</secondary></indexterm>
                <para>Text box with 2 compartments. 
                This allows you to set 
                an initial value for the attribute if desired (this is 
                optional). The drop down menu provides access to the 
                common values <literal>0</literal>, <literal>
                1</literal>, <literal>2</literal>, and <literal>
                null</literal>.</para>
                
                <para>The left hand side of this field contains 
                the body of the expression that forms the initial value.
                The right hand side defines 
                the language in which the expression is written.</para>
                
                <para>Hovering the mouse pointer over these fields, 
                reveals a tooltip <literal>Body</literal> or 
                <literal>Language</literal>, 
                to help remember which is which.</para>

                <caution>

                  <para>Any constructor operation may ignore this 
                  initial value.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.operation">

        <title>Operation</title>

        <indexterm><primary>Operation</primary></indexterm>
        <para>An operation is a service that can be requested from an 
        object to effect behavior. In the UML metamodel it is a 
        sub-class of <literal>BehavioralFeature</literal> which is 
        itself a sub-class of <literal>Feature</literal>.</para>

        <para>In the diagram, an operation is represented on a single 
        line within the operation compartment of the class. Its syntax 
        is as follows:</para>

        <blockquote>

          <para>visibility name (parameter list) : 
          return-type-expression {property-string}</para>

        </blockquote>

        <para>You can edit this line directly in the diagram, by 
        double-clicking on it. All elements are optional and, if left 
        unspecified, the old values will be preserved.</para>

        <para>A <emphasis>stereotype</emphasis> can be given between 
        any two elements in the line in the format: <literal>
        &lt;&lt;stereotype&gt;&gt;</literal>.</para>

        <para>The following properties are recognized to have special 
        meaning: abstract, concurrency, concurrent, guarded, leaf, 
        query, root and sequential.</para>

        <para>The <emphasis>visibility</emphasis> is <literal>
        +</literal>, <literal>#</literal>, <literal>-</literal> or
        <literal>~</literal> 
        corresponding to <literal>public</literal>, <literal>
        protected</literal>, <literal>private</literal> visibility,
        or <literal>package</literal> visibility 
        respectively.</para>

        <para><literal>static</literal> and <literal>final</literal> 
        optionally appear if the operation has those modifiers. Any 
        operation declared static will have its whole entry underlined 
        on the diagram.</para>

        <para>There may be zero or more entries in the 
        <emphasis>parameter list</emphasis> separated by commas. Every 
        entry is a pair of the form:</para>

        <blockquote>

          <para><emphasis>name</emphasis> <literal>:</literal> 
          <emphasis>type</emphasis></para>

        </blockquote>

        <para>The <emphasis>return-type-expression</emphasis> is the 
        type (UML datatype, class or interface) of the result 
        returned.</para>

        <para>Finally the whole entry is shown in italics if the 
        operation is declared abstract.</para>

        <sect2>

          <title>Operation Details Tabs</title>

          <indexterm><primary>Operation Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Operation</secondary></indexterm>
          <para>The details tabs that are active for operations are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.operation_property_toolbar"/> and 
                <xref linkend="s2.ref.operation_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The <literal>Bounds:</literal> 
                field does allow editing, but the changes have no 
                effect.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This contains a declaration for the 
                operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Constraints</literal></term>

              <listitem>

                <para>Standard tab. There are no standard constraints 
                defined for <literal>Operation</literal> within the UML 
                metamodel.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Operation Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Operation</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>semantics</literal>. The value is a 
                    specification of the semantics of the 
                    operation.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    operation is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived operations still have their value 
                      in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for an Operation.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.operation_property_toolbar">

          <title>Operation Property Toolbar</title>

          <indexterm><primary>Operation Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Operation</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New operation</literal></term>

              <listitem>

                <para>This creates a new operation within the owning 
                class of the current operation, navigating immediately 
                to the properties tab for that operation.</para>

                <tip>

                  <para>This is a very convenient way to add a number 
                  of operations, one after the other, to a class.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/parameter.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New parameter</literal></term>

              <listitem>

                <para>This creates a new parameter for the operation, 
                navigating immediately to the properties tab for that 
                parameter.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/signal.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New raised signal</literal></term>

              <listitem>

                <para>This creates a new raised signal for the 
                operation, navigating immediately to the properties tab 
                for that raised signal.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Datatype</literal></term>

              <listitem>

                <indexterm><primary>Add Datatype</primary></indexterm>
                <indexterm><primary>New Datatype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Datatype</secondary></indexterm>
                <para>This creates a new Datatype (see 
                <xref linkend="s1.ref.datatype"/>) in the namespace of 
                the owner of the operation, navigating immediately to 
                the properties tab for that datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                operation, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the operation from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. If desired 
                  the whole operation compartment can be hidden on the 
                  diagram using the <emphasis>presentation</emphasis> 
                  tab (see 
                  <xref linkend="s2.ref.operation_property_toolbar"/>) 
                  or the button&nbsp;2 pop up menu for the class on the 
                  diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.operation_property_fields">

          <title>Property Fields For Operation</title>

          <indexterm><primary>Operation Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Operation</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Operation Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Text box. The name of the operation. The name of 
                an operation has a leading lower case letter, with 
                words separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>The ArgoUML critics will complain about 
                  operation names that do not have an initial lower 
                  case letter.</para>

                </note>

                <tip>

                  <para>If you wish to follow the Java convention of 
                  constructors having the same name as the class, you 
                  will violate this rule. Silence the critic by setting 
                  the stereotype <literal>create</literal> for the 
                  constructor operation.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Operation 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Drop down selector. There are two UML standard 
                stereotypes for <literal>Operation</literal> (from the 
                parent metaclass, <literal>
                BehavioralFeature</literal>), <literal>create</literal> 
                and <literal>destroy</literal>.</para>

                <tip>

                  <para>You should use <literal>create</literal> as the 
                  stereotype for constructors, and <literal>
                  destroy</literal> for destructors (which are called 
                  <quote>finalize</quote> methods under Java).</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, clicking 
                button&nbsp;1 will navigate to the stereotype property panel 
                (see <xref linkend="s1.ref.stereotype_class"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owner</literal></term>

              <listitem>

                <para>Text box. Records the class which contains this 
                operation.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the class.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Operation 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Radio box, with entries <literal>
                public</literal>, <literal>private</literal>,  
                <literal>protected</literal> and
                <literal>package</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>public</literal>. The operation is 
                    available to any model element that can see the owning 
                    class.</para>

                  </listitem>

                  <listitem>

                    <para><literal>private</literal>. The operation is 
                    available only to the owning class (and any inner 
                    classes).</para>

                  </listitem>

                  <listitem>

                    <para><literal>protected</literal>. The operation 
                    is available only to the owning class, or model elements 
                    that are subclasses of the owning class.</para>

                  </listitem>
                  <listitem>

                    <para><literal>package</literal>. The operation 
                    is available only model elements contained in the 
                    same package.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Operation 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Check box, with entries <literal>
                abstract</literal>, <literal>leaf</literal>, <literal>
                root</literal>, <literal>query</literal>, and <literal>
                static</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>abstract</literal>. This operation 
                    has no implementation with this class. The 
                    implementation must be provided by a 
                    subclass.</para>

                    <important>

                      <para>Any class with an abstract operation must 
                      itself be declared abstract.</para>

                    </important>

                  </listitem>

                  <listitem>

                    <para><literal>leaf</literal>. The implementation 
                    of this operation must not be overridden by any 
                    subclass.</para>

                  </listitem>

                  <listitem>

                    <para><literal>root</literal>. The declaration of 
                    this operation must not override a declaration of 
                    the operation from a superclass.</para>

                  </listitem>

                  <listitem>

                    <para><literal>query</literal>. This indicates that 
                    the operation must have no side effects (i.e. it 
                    must not change the state of the system). It can 
                    only return a value.</para>

                    <caution>

                      <para>Operations for user defined datatypes must 
                      always check this modifier.</para>

                    </caution>

                  </listitem>

                  <listitem>

                    <para><literal>static</literal>. There is only one 
                    instance of this operation associated with the 
                    class (as opposed to one for each instance of the 
                    class). This is the <literal>OwnerScope</literal> 
                    attribute of a <literal>Feature</literal> metaclass 
                    within UML. Any operation declared static is shown 
                    underlined on the class diagram.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Concurrency</literal></term>

              <listitem>

                <indexterm><primary>Operation 
                Concurrency</primary></indexterm>
                <indexterm><primary>Concurrency</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Radio box, with entries <literal>
                guarded</literal>, <literal>sequential</literal>, and 
                <literal>concurrent</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>guarded</literal>. Multiple calls 
                    from concurrent threads may occur simultaneously to 
                    one instance (on any guarded operation), but only 
                    one is allowed to commence. The others are blocked 
                    until the performance of the first operation is 
                    complete.</para>

                    <caution>

                      <para>It is up to the system designer to ensure 
                      that deadlock cannot occur. It is the 
                      responsibility of the operation to implement the 
                      blocking behavior (as opposed to the 
                      system).</para>

                    </caution>

                  </listitem>

                  <listitem>

                    <para><literal>sequential</literal>. Only one call 
                    to an instance (of the class with the operation) 
                    may be outstanding at any one time. There is no 
                    protection, and no guarantee of behavior if the 
                    system violates this rule.</para>

                  </listitem>

                  <listitem>

                    <para><literal>concurrent</literal>. Multiple calls 
                    to one instance may execute at the same time. The 
                    operation is responsible for ensuring correct 
                    behavior. This must be managed even if there are 
                    other sequential or synchronized (guarded) 
                    operations executing at the time.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Parameter</literal></term>

              <listitem>

                <indexterm><primary>Operation 
                Parameter</primary></indexterm>
                <indexterm><primary>Parameter</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Text area, with entries for all the parameters of 
                the operation (see <xref linkend="s1.ref.parameter"/>). 
                A new operation is always created with one new 
                parameter, <literal>return</literal> to define the 
                return type of the operation.</para>

                <para>Button&nbsp;1 double click on any of the parameters 
                navigates to that parameter. Button&nbsp;2 click brings up a 
                pop up menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Move Up</literal>. Only available 
                    where there are two or more parameters, and the 
                    parameter selected is not at the top. It is moved 
                    up one position.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Move Down</literal>. Only available 
                    where there are two or more parameters listed, and 
                    the parameter selected is not at the bottom. It is 
                    moved down one position.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Raised Signals</literal></term>

              <listitem>

                <indexterm><primary>Operation Raised 
                Signals</primary></indexterm>
                <indexterm><primary>Raised 
                Signals</primary><secondary>of 
                Operation</secondary></indexterm>
                <para>Text area, with entries for all the signals (see 
                <xref linkend="s1.ref.signal"/>) that can be raised by 
                the operation.</para>

                <caution>

                  <para>ArgoUML at present (V0.18) has limited support 
                  for signals. In particular they are not linked to 
                  signal events that could drive state machines.</para>

                </caution>

                <para>Button&nbsp;1 double click on any of the signals 
                navigates to that parameter.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.parameter">

        <title>Parameter</title>

        <indexterm><primary>Parameter</primary></indexterm>
        <para>A parameter is a variable that can be passed. In the UML 
        metamodel it is a sub-class of <literal>
        ModelElement</literal>.</para>

        <para>A parameter is represented within the operation 
        declaration in the operation compartment of a class as 
        follows.</para>

        <blockquote>

          <para><emphasis>name</emphasis> <literal>:</literal> 
          <emphasis>type</emphasis></para>

        </blockquote>

        <para><emphasis>name</emphasis> is the name of the 
        parameter.</para>

        <para><emphasis>type</emphasis> is the type (UML datatype, 
        class or interface) of the parameter.</para>

        <para>The exception is any parameter representing a return 
        value, whose type only is shown at the end of the operation 
        declaration.</para>

        <sect2>

          <title>Parameter Details Tabs</title>

          <indexterm><primary>Parameter Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Parameter</secondary></indexterm>
          <para>The details tabs that are active for parameters are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.parameter_property_toolbar"/> and 
                <xref linkend="s2.ref.parameter_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This contains a declaration for the 
                parameter.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Parameter Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Parameter</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    parameter is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <caution>

                      <para>A derived parameter is a meaningless 
                      concept.</para>

                    </caution>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.parameter_property_toolbar">

          <title>Parameter Property Toolbar</title>

          <indexterm><primary>Parameter Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Parameter</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/parameter.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New parameter</literal></term>

              <listitem>

                <para>This creates a new parameter for the for the same 
                operation as the current parameter, navigating 
                immediately to the properties tab for that 
                parameter.</para>

                <tip>

                  <para>This is a convenient way to add a series of 
                  parameters for the same operation.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/datatype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Datatype</literal></term>

              <listitem>

                <indexterm><primary>Add Datatype</primary></indexterm>
                <indexterm><primary>New Datatype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Datatype</secondary></indexterm>
                <para>This creates a new Datatype (see 
                <xref linkend="s1.ref.datatype"/>) in the namespace of 
                the owner of the operation of the parameter, navigating 
                immediately to the properties tab for that 
                datatype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                parameter, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the parameter from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. If desired 
                  the whole operation compartment can be hidden on the 
                  diagram using the <emphasis>presentation</emphasis> 
                  tab or the button&nbsp;2 pop up menu for the class on the 
                  diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.parameter_property_fields">

          <title>Property Fields For Parameter</title>

          <indexterm><primary>Parameter Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Parameter</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Parameter Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Text box. The name of the parameter. By 
                convention, the name of a parameter has a leading lower 
                case letter, with words separated by <quote>bumpy 
                caps</quote>.</para>

                <note>

                  <para>The ArgoUML critics do not complain about 
                  parameter names that do not have an initial lower 
                  case letter.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Parameter 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Drop down selector. There are no UML standard 
                stereotypes for <literal>Parameter</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Owner</literal></term>

              <listitem>

                <para>Text box. Records the operation which contains 
                this parameter.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Type</literal></term>

              <listitem>

                <indexterm><primary>Parameter Type</primary></indexterm>
                <indexterm><primary>Type</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Drop down selector. The type of this parameter. 
                This can be any UML <literal>Classifier</literal>, 
                although in practice only <literal>Class</literal>, 
                <literal>DataType</literal>, or <literal>
                Interface</literal> make any sense.</para>

                <note>

                  <para>A type must be declared (it can be <literal>
                  void</literal>, but this only makes sense for a 
                  return parameter). By default ArgoUML supplies 
                  <literal>int</literal> as the type the first time a 
                  parameter is created, and thereafter the type of the 
                  most recently created parameter.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Default Value</literal></term>

              <listitem>

                <indexterm><primary>Parameter Initial 
                Value</primary></indexterm>
                <indexterm><primary>Initial 
                Value</primary><secondary>of 
                Parameter</secondary></indexterm>
                <indexterm><primary>Parameter Default 
                Value</primary></indexterm>
                <indexterm><primary>Default 
                Value</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Text box with drop down. This allows you to set 
                an initial value for the parameter if desired (this is 
                optional). The drop down menu provides access to the 
                common values <literal>0</literal>, <literal>
                1</literal>, <literal>2</literal>, and <literal>
                null</literal>.</para>

                <caution>

                  <para>This only makes sense for <literal>
                  out</literal> or <literal>return</literal> 
                  parameters.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Kind</literal></term>

              <listitem>

                <indexterm><primary>Parameter Kind</primary></indexterm>
                <indexterm><primary>Kind</primary><secondary>of 
                Parameter</secondary></indexterm>
                <para>Radio box, with entries <literal>out</literal>, 
                <literal>in/out</literal>, <literal>return</literal>, 
                and <literal>in</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>out</literal>. The parameter is used 
                    only to pass values back from the operation.</para>

                  </listitem>

                  <listitem>

                    <para><literal>in/out</literal>. The parameter is 
                    used both to pass values in and to pass results 
                    back out of the operation.</para>

                    <note>

                      <para>This is the default for any new 
                      parameter.</para>

                    </note>

                  </listitem>

                  <listitem>

                    <para><literal>return</literal>. The parameter is a 
                    return result from the call.</para>

                    <note>

                      <para>There is nothing to stop you declaring more 
                      than one return parameter (some programming 
                      languages support this concept).</para>

                    </note>

                    <tip>

                      <para>The name of the return parameter does not 
                      appear on the diagram, but it is convenient to 
                      give it an appropriate name (such as the default 
                      <literal>return</literal> to identify it in the 
                      list of parameters on the operation property 
                      tab.</para>

                    </tip>

                  </listitem>

                  <listitem>

                    <para><literal>in</literal>. The parameter is used 
                    only to pass values in to the operation.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.signal">

        <title>Signal</title>

        <indexterm><primary>Signal</primary></indexterm>
        <para>A signal is a specification of an asynchronous stimulus 
        communicated between instances. In the UML metamodel it is a 
        sub-class of <literal>Classifier</literal>.</para>

        <para>Within ArgoUML signals are not fully handled. Their value 
        is when they are received as <emphasis>signal events</emphasis> 
        driving the asynchronous behavior of state machines and when 
        associated with <emphasis>send actions</emphasis> in state 
        machines and messages for collaboration diagrams.</para>

        <tip>

          <para>In general there is limited value at present in 
          defining signals within ArgoUML. It may prove more useful to 
          define signals as classes, with a (user defined) stereotype 
          of <literal>&laquo;signal&raquo;</literal> as suggested in the UML 1.4 
          standard. This allows any dependency relationships between 
          signals to be shown.</para>

        </tip>

        <sect2>

          <title>Signal Details Tabs</title>

          <indexterm><primary>Signal Details Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Signal</secondary></indexterm>
          <para>The details tabs that are active for signals are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.signal_property_toolbar"/> and 
                <xref linkend="s2.ref.signal_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. There is nothing generated for a 
                signal.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Signal Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Signal</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Signal</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    signal.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the signal 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived signals still have their value in 
                      analysis to introduce useful names or concepts, 
                      and in design to avoid re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.signal_property_toolbar">

          <title>Signal Property Toolbar</title>

          <indexterm><primary>Signal Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Signal</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/signal.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New signal</literal></term>

              <listitem>

                <para>This creates a new signal, navigating immediately 
                to the properties tab for that signal.</para>

                <caution>

                  <para>The signal is not associated with the same 
                  operation as the original signal, so this will have 
                  to be done afterwards.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                signal, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the signal from the model</para>

                <warning>

                  <para>This is a deletion from the model.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.signal_property_fields">

          <title>Property Fields For Signal</title>

          <indexterm><primary>Signal Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Signal</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Signal Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Signal</secondary></indexterm>
                <para>Text box. The name of the signal. From their 
                similarity to classes, by convention, the name of a 
                signal has a leading upper case letter, with words 
                separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>The ArgoUML critics do not complain about 
                  signal names that do not have an initial upper case 
                  letter.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Signal 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Signal</secondary></indexterm>
                <para>Drop down selector. Signal is provided by default 
                with the UML standard stereotypes for its parent in the 
                UML meta-model, <literal>Classifier</literal> (
                <literal>metaclass</literal>, <literal>
                powerType</literal>, <literal>process</literal>, 
                <literal>thread</literal>, and <literal>
                utility</literal>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows changing 
                the namespace for the signal. This is the package 
                hierarchy of the signal.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Contexts</literal></term>

              <listitem>

                <indexterm><primary>Signal 
                Contexts</primary></indexterm>
                <indexterm><primary>Contexts</primary><secondary>of 
                Signal</secondary></indexterm>
                <para>Text area. Lists all the contexts defined for 
                this signal. Button&nbsp;1 double click navigates to the 
                selected context, button&nbsp;2 click brings up a pop up 
                menu with one entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. Add a new context. 
                    This opens the <emphasis>Add/Remove 
                    Contexts</emphasis> dialog box (see figure below), 
                    which allows choosing between all possible 
                    operations, and adding them to the selected 
                    list.</para>

                    <figure float="1" id="fig.ref.signal_add_context">

                      <title>The <quote>add/remove context</quote> 
                      dialog box</title>

                      <screenshot><mediaobject><imageobject>
                      <imagedata align="center"
                       fileref="images/reference/signal_add_context.png"
                       format="PNG"/></imageobject></mediaobject></screenshot>
                    </figure>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.reception">

        <title>Reception (to be written)</title>

        <para>A reception is ...</para>

      </sect1>

      <sect1 id="s1.ref.association_class">

        <title>Association</title>

        <indexterm><primary>Association</primary></indexterm>
        <para>An association on a class diagram represents a 
        relationship between classes, or between a class and an 
        interface. On a usecase diagram, an association binds an actor 
        to a usecase.</para>

        <para>Within the UML metamodel, <literal>Association</literal> 
        is a sub-class of both <literal>Relationship</literal> and 
        <literal>GeneralizableElement</literal>.</para>

        <para>The association is represented as a solid line connecting 
        actor and usecase or class or interface (see 
        <xref linkend="fig.ref.class_diagram"/>). The name of the 
        association and any stereotype appear above the line.</para>

        <para>ArgoUML is not restricted to binary associations. See 
        <xref linkend="s2.ref.association_multiway"/> for more on 
        this.</para>

        <para>Associations are permitted between interfaces and 
        classes, but UML&nbsp;1.3 specifies they must only be navigable 
        toward the interface&mdash;in other words the interface cannot see 
        the class. ArgoUML will draw such associations with the 
        appropriate navigation.</para>

        <para>Associations are often not named, when their meaning is 
        obvious from the context.</para>

        <note>

          <para>ArgoUML provides no specific way of showing the 
          direction of the association as described in the UML 1.4 
          standard. The naming should attempt to make this clear.</para>

        </note>

        <para>The association contains at least two ends, which may be 
        navigated to via the association property sheet. See 
        <xref linkend="s1.ref.association_end_class"/> for more 
        information.</para>

        <sect2 id="s2.ref.association_multiway">

          <title>Three-way and Greater Associations and Association 
          Classes</title>

          <para>UML&nbsp;1.3 provides for N-ary associations and 
          associations that are governed by a third 
          <emphasis>associative class</emphasis>. Both are supported by 
          ArgoUML.</para>

          <para><emphasis>N-ary associations</emphasis> are created by 
          drawing with the association tool from an existing 
          association to a third class. The current implementation of 
          ArgoUML does not allow the inverse: drawing from a 3rd class 
          towards an existing association is not possible.</para>

          <para>Association Classes are drawn exactly like a normal 
          association, i.e. between two classes, but with a different 
          dedicated tool from the diagram toolbar.</para>

        </sect2>

        <sect2>

          <title>Association Details Tabs</title>

          <para>The details tabs that are active for associations are 
          as follows.</para>

          <indexterm><primary>Association Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Association</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.association_property_toolbar"/> 
                and <xref linkend="s2.ref.association_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>The values for the bounds of the Association 
                  have no meaning, since they are determined by the 
                  location of the connected items. Changing them has no 
                  effect on the diagram.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. You would not expect to generate 
                any code for an association, and any code entered here 
                is ignored (it will have disappeared when you come back 
                to the association.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Association Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of 
                Association</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                Association</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal>. Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    association is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived associations still have their value 
                      in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_property_toolbar">

          <title>Association Property Toolbar</title>

          <indexterm><primary>Association Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Association</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model. For an association this will be the package 
                containing the association.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                association, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected association from the 
                model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an association from the diagram, but keep it within 
                  the model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_property_fields">

          <title>Property Fields For Association</title>

          <indexterm><primary>Association Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Association</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Association 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Association</secondary></indexterm>
                <para>Text box. The name of the association. By 
                convention association names start with a lower case 
                letter, with <quote>bumpy caps</quote> used to indicate 
                words within the name, thus: <literal>
                salesHandling</literal>.</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for associations.</para>

                </note>

                <tip>

                  <para>Although the design critics will advise 
                  otherwise, it is perfectly normal not to name 
                  associations on a class diagram, since the 
                  relationship is often obvious from the classes (or 
                  class and interface) name.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Association 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Association</secondary></indexterm>
                <para>Drop down selector. Association is provided by 
                default with the UML standard stereotype for 
                Association (<literal>implicit</literal>) .</para>

                <para>Stereotyping can be useful when creating 
                associations in the problem domain (requirements 
                capture) and solution domain (analysis), as well as for 
                processes based on patterns.</para>

                <para>The stereotype is shown between &laquo; and &raquo; below the 
                name of the association on the diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows changing 
                the namespace for the association. This is the package 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Connections</literal></term>

              <listitem>

                <indexterm><primary>Association 
                Ends</primary><secondary>of 
                Association</secondary></indexterm>
                <indexterm><primary>Connections</primary><secondary>of 
                Association</secondary></indexterm>
                <para>Text area. Lists the ends of this association. An 
                association can have two or more ends. For more on 
                association ends see 
                <xref linkend="s1.ref.association_end_class"/>.</para>

                <para>The names of the association ends are listed, 
                unless the association end has no name (the case when 
                it is first created), in which case <literal>(Unnamed 
                AssociationEnd)</literal> is shown.</para>

                <note>

                  <para>The only representation of association ends on 
                  a diagram is that their name appears at the relevant 
                  end of the corresponding association.</para>

                </note>

                <para>Button&nbsp;1 double click on an association end will 
                navigate to that end.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association Roles</literal></term>

              <listitem>

                <para>Text area. (To be written)</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Links</literal></term>

              <listitem>

                <para>Text area. (To be written)</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.association_end_class">

        <title>Association End</title>

        <indexterm><primary>Association End</primary></indexterm>
        <para>Two or more association ends are associated with each 
        association (see <xref linkend="s1.ref.association_use_case"/>
        ).</para>

        <para>Within the UML metamodel, <literal>
        AssociationEnd</literal> is a sub-class of <literal>
        ModelElement</literal>.</para>

        <para>The association end has no direct access on any diagram 
        for binary associations. The ends of an N-ary association may 
        be selected by clicking on the line in the diagram. The 
        stereotype, name and multiplicity are shown at the relevant end 
        of the parent association (see 
        <xref linkend="fig.ref.use_case_diagram"/>). Where shared or 
        composite aggregation is selected for one association end, the 
        opposite end is shown as a solid diamond (composite 
        aggregation) or hollow diamond (shared aggregation).</para>

        <tip>

          <para>Although you can change attributes of association ends 
          when creating a use case model, this is often not necessary. 
          Many of the properties of an association end relate to its 
          use in class diagrams, and are of limited relevance to use 
          cases. The most useful attributes to consider altering are 
          the name (used as the role name) and the multiplicity.</para>

        </tip>

        <note>

          <para>ArgoUML does not currently support showing qualifiers 
          on the diagram, as described in the UML&nbsp;1.3 standard.</para>

        </note>

        <sect2>

          <title>Association End Details Tabs</title>

          <para>The details tabs that are active for associations are 
          as follows.</para>

          <indexterm><primary>Association End Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Association End</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.association_end_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.association_end_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This tab contains a declaration for 
                the association end as an instance of the model element to 
                which it is connected.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <indexterm><primary>Association End Tagged 
                Values</primary></indexterm>
                <indexterm><primary>Tagged 
                Values</primary><secondary>of Association 
                End</secondary></indexterm>
                <para>Standard tab. In the UML metamodel, <literal>
                AssociationEnd</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    association end is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <tip>

                      <para>Derived association ends still have their 
                      value in analysis to introduce useful names or 
                      concepts, and in design to avoid re-computation. 
                      However the tag only makes sense for an 
                      association end if it is also applied to the 
                      parent association.</para>

                    </tip>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_end_property_toolbar">

          <title>Association End Property Toolbar</title>

          <indexterm><primary>Association End Property 
          Toolbar</primary></indexterm>
          <indexterm><primary>Property Toolbar</primary><secondary>for 
          Association End</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up to the association to which this end 
                belongs.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_end.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go Opposite</literal></term>

              <listitem>

                <para>This navigates to the other end of the 
                association.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Qualifier</literal></term>

              <listitem>

                <indexterm><primary>Add Qualifier</primary></indexterm>
                <indexterm><primary>New Qualifier</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Qualifier</secondary></indexterm>
                <para>This creates a new Qualifier for the selected 
                association-end, navigating immediately to the 
                properties tab for that qualifier.</para>

                <warning>

                  <para>Qualifiers are only partly supported in ArgoUML 
                  V0.18. Hence, activating this button creates a 
                  qualifier in the model, which is not shown on the 
                  diagram. Also, the properties panel for a qualifier 
                  equals that of a regular attribute.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                association-end, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected association-end from 
                the model.</para>

                <note>

                  <para>This button is downlighted for binary 
                  associations, since an association needs at least 
                  <emphasis>two</emphasis> ends. Only for N-ary 
                  associations, this button is accessable, and deletes 
                  just one end from the association.</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_end_property_fields">

          <title>Property Fields For Association End</title>

          <indexterm><primary>Association End Property 
          Fields</primary></indexterm>
          <indexterm><primary>Property Fields</primary><secondary>for 
          Association End</secondary></indexterm>
          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Text box. The name of the association end, which 
                provides a <emphasis>role name</emphasis> for this end 
                of the association. This role name can be used for 
                navigation, and in an implementation context, provides 
                a name by which the source end of an association can 
                reference the target end.</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for association ends.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Drop down selector. Association end is provided 
                by default with the UML standard stereotypes for 
                AssociationEnd (<literal>association</literal>, 
                <literal>global</literal>, <literal>local</literal>, 
                <literal>parameter</literal>, <literal>
                self</literal>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association</literal></term>

              <listitem>

                <para>Text box. Records the parent association for this 
                association end. Button&nbsp;1 double click on this entry 
                will navigate to that association.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Type</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Type</primary></indexterm>
                <indexterm><primary>Type</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Drop down selector providing access to all 
                standard UML types provided by ArgoUML and all new 
                classes created within the current model.</para>

                <para>This is the type of the entity attached to this 
                end of the association.</para>

                <tip>

                  <para>By default ArgoUML will select the class of the 
                  model element to which the linkend is connected. However, 
                  an association can be moved to another class by 
                  selecting another entry here.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Multiplicity</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Multiplicity</primary></indexterm>
                <indexterm><primary>Multiplicity</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Drop down menu with edit box. The value can be 
                chosen from the drop down box, or a new one can be 
                edited in the text box. Records the multiplicity of 
                this association end (with respect to the other end), 
                i.e. how many instances of this end may be associated 
                with an instance of the other end. The multiplicity is 
                shown on the diagram at that end of the 
                association.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Modifiers</primary></indexterm>
                <indexterm><primary>Modifiers</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>There are 3 modifiers: <literal>
                navigable</literal>, <literal>ordered</literal> and 
                <literal>static</literal>. All 3 are checkboxes.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>navigable</literal>. Indicates that 
                    this end can be navigated to from the other 
                    end.</para>

                    <note>

                      <para>The UML 1.4 standard provides a number of 
                      options for how navigation is displayed on an 
                      association end. ArgoUML uses option 3, which 
                      means that arrow heads are shown at the end of an 
                      association, when navigation is enabled at only 
                      one end, to indicate the direction in which 
                      navigation is possible. This means that the 
                      default, with both ends navigable has no 
                      arrows.</para>

                    </note>

                  </listitem>

                  <listitem>

                    <para><literal>ordered</literal> When placed on one 
                    end, specifies whether the set of links from the 
                    other instance to this instance is ordered. The 
                    ordering must be determined and maintained by 
                    Operations that add links. It represents additional 
                    information not inherent in the objects or links 
                    themselves. Possibilities for the checkbox are: 
                    Unchecked - The links form a set with no inherent 
                    ordering. Checked - A set of ordered links can be 
                    scanned in order.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Static</literal> (To be 
                    written)</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specification</literal></term>

              <listitem>

                <para>List. Designates zero or more Classifiers that 
                specify the Operations that may be applied to an 
                Instance accessed by the AssociationEnd across the 
                Association. These determine the minimum interface that 
                must be realized by the actual Classifier attached to 
                the end to support the intent of the Association. May 
                be an Interface or another Classifier. The type of 
                classifier is indicated by an icon.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                classifier, button&nbsp;2 click brings a pop up menu with 
                one entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. Add a new 
                    specification classifier. This opens the 
                    <emphasis>Add/Remove Specifications</emphasis> 
                    dialog box (see figure below), which allows 
                    choosing between all possible classifiers, and 
                    adding or removing them to the selected list.</para>

                    <figure float="1" id="fig.ref.signal_add_specification">

                      <title>The <quote>Add/Remove 
                      Specifications</quote> dialog box</title>

                      <screenshot><mediaobject><imageobject>
                      <imagedata align="center"
                       fileref="images/reference/signal_add_specification.png"
                       format="PNG"/></imageobject></mediaobject></screenshot>
                    </figure>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Qualifiers</literal></term>

              <listitem>

                <para>Text box. Records the qualifiers for this 
                association end. Button&nbsp;1 double click on this entry 
                will navigate to that qualifier. Button&nbsp;2 click will 
                show a popup menu containing two items: <literal>Move 
                Up</literal> and <literal>Move Down</literal>, which 
                allow reordering the qualifiers.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Aggregation</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Aggregation</primary></indexterm>
                <indexterm><primary>Aggregation</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Radio box, with three entries <literal>
                composite</literal>, <literal>none</literal> and 
                <literal>aggregate</literal>. Indicates whether the 
                relationship with the far end represents some type of 
                loose whole-part relationship (
                <literal>aggregation</literal>) or tight whole-part 
                relationship (<literal>composite</literal>).</para>

                <para>Shared aggregation is shown by a hollow diamond 
                at the <quote>whole</quote> end of the association. 
                Composite aggregation is shown by a solid 
                diamond.</para>

                <note>

                  <para>You may not have aggregation at both ends of an 
                  association. ArgoUML does not enforce this 
                  constraint.</para>

                  <para>The <quote>whole</quote> end of a composite 
                  aggregation should have a multiplicity of one. 
                  ArgoUML does not enforce this constraint.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Changeability</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Changeability</primary></indexterm>
                <indexterm>
                <primary>Changeability</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Radio box, with three entries <literal>add 
                only</literal>, <literal>changeable</literal> and 
                <literal>frozen</literal>. Indicates whether instances 
                of this end of the association-end may be: i) created 
                but not deleted after the target instance is created; 
                ii) created and deleted by the source after the target 
                instance is created; or iii) not created or deleted by 
                the source after the target instance is created.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <indexterm><primary>Association End 
                Visibility</primary></indexterm>
                <indexterm><primary>Visibility</primary><secondary>of 
                Association End</secondary></indexterm>
                <para>Radio box, with four entries <literal>
                public</literal>, <literal>private</literal>,  
                <literal>protected</literal>, and 
                <literal>package</literal>. Indicates whether 
                navigation to this end may be by: i) any classifier; 
                ii) only by the source classifier; or iii) only the 
                source classifier and its children.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.dependency_class">

        <title>Dependency</title>

        <indexterm><primary>Dependency</primary></indexterm>
        <para>Dependency is a relationship between two model elements 
        showing that one depends on the other.</para>

        <para>Within the UML metamodel, <literal>Dependency</literal> 
        is a sub-class of <literal>Relationship</literal>.</para>

        <para>Dependency is represented as a dashed line with an open 
        arrow head from the depending model element to that which it is 
        dependent upon.</para>

        <sect2>

          <title>Dependency Details Tabs</title>

          <indexterm><primary>Dependency Details 
          Tabs</primary></indexterm>
          <indexterm><primary>Details Tabs</primary><secondary>for 
          Dependency</secondary></indexterm>
          <para>The details tabs that are active for dependencies are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.dependency_property_toolbar"/> 
                and <xref linkend="s2.ref.dependency_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab</para>

                <note>

                  <para>
                    The values in the "bounds" field of the 
                    dependency
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Dependency</literal> has no tagged values of its own, 
                but through superclasses has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    dependency relationship is redundant&mdash;it can be 
                    formally derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>Derived dependencies still have their value 
                      in analysis to introduce useful names or 
                      concepts.</para>

                    </note>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.dependency_property_toolbar">

          <title>Dependency Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure of the 
                model. For a dependency this will be the package 
                containing the dependency.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                dependency, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected dependency from the 
                model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a dependency from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.dependency_property_fields">

          <title>Property Fields For Dependency</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <indexterm><primary>Dependency 
                Name</primary></indexterm>
                <indexterm><primary>Name</primary><secondary>of 
                Dependency</secondary></indexterm>
                <para>Text box. The name of the dependency.</para>

                <tip>

                  <para>It is quite common to leave dependencies 
                  unnamed.</para>

                </tip>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for associations.</para>

                </note>

                <note>

                  <para>There is no representation of the name of a 
                  dependency on the diagram.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Dependency 
                Stereotype</primary></indexterm>
                <indexterm><primary>Stereotype</primary><secondary>of 
                Dependency</secondary></indexterm>
                <para>Drop down selector. Dependency has no standard 
                stereotypes of its own under UML&nbsp;1.3. and so ArgoUML 
                does not provide any. The stereotype is shown between  &laquo;
                and &raquo; above or across the generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <indexterm><primary>Dependency 
                Namespace</primary></indexterm>
                <indexterm><primary>Namespace</primary><secondary>of 
                Dependency</secondary></indexterm>
                <para>Text box. Records the namespace for the 
                dependency. This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Suppliers</literal></term>

              <listitem>

                <indexterm><primary>Dependency 
                Suppliers</primary></indexterm>
                <indexterm><primary>Suppliers</primary><secondary>of 
                Dependency</secondary></indexterm>
                <para>Text area. Lists the end of the relationship that 
                is supplying what is needed by the other end.</para>

                <para>Button&nbsp;1 double click on a supplier will navigate 
                to that element.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Clients</literal></term>

              <listitem>

                <indexterm><primary>Dependency 
                Clients</primary></indexterm>
                <indexterm><primary>Clients</primary><secondary>of 
                Dependency</secondary></indexterm>
                <para>Text area. Lists the <quote>depending</quote> 
                ends of the relationship, i.e. the end that makes use 
                of the other end.</para>

                <para>Button&nbsp;1 double click on a client will navigate 
                to that element.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.generalization_class">

        <title>Generalization</title>

        <para>Generalization is described under use case diagrams (see 
        <xref linkend="s1.ref.generalization_use_case"/>).</para>

        <note>

          <para>Within the context of classes, generalization and 
          specialization are the UML terms describing class 
          inheritance.</para>

        </note>

      </sect1>

      <sect1 id="s1.ref.interface_class">

        <title>Interface</title>

        <para>An interface is a set of operations characterizing the 
        behavior of an element. It can be usefully thought of as an 
        abstract class with no attributes and no non-abstract 
        operations. In the UML metamodel it is a sub-class of <literal>
        Classifier</literal> and through that <literal>
        GeneralizableElement</literal>.</para>

        <para>An interface is represented on a class diagram as a 
        rectangle with two horizontal compartments. The top compartment 
        displays the interface name (and above it <literal>
        &laquo;interface&raquo;</literal>) and the second any operations. Just like 
        a class, the operations compartment can be hidden.</para>

        <sect2>

          <title>Interface Details Tabs</title>

          <para>The details tabs that are active for interfaces are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.interface_property_toolbar"/> and 
                <xref linkend="s2.ref.interface_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The tick box <literal>Display 
                Operations</literal> allows the operation compartment 
                to be shown (the default) or hidden. This is a setting 
                valid for only the current diagram. The <literal>
                Bounds:</literal> field defines the bounding box for 
                the package on the diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This contains a template for the 
                interface declaration and declarations of associated 
                interfaces.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Interface</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                    <warning>

                      <para>Since interfaces are by definition 
                      abstract, they can have no instance, and so this 
                      tagged value must refer to the properties of the 
                      realizing class.</para>

                    </warning>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    interface.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    interface is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived interfaces still have their value 
                      in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for an Interface.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.interface_property_toolbar">

          <title>Interface Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/operation.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New operation</literal></term>

              <listitem>

                <para>This creates a new operation (see 
                <xref linkend="s1.ref.operation"/>) within the 
                interface, navigating immediately to the properties tab 
                for that operation.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New reception</literal></term>

              <listitem>

                <para>This creates a new reception, navigating 
                immediately to the properties tab for that 
                reception.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/interface.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New interface</literal></term>

              <listitem>

                <para>This creates a new interface in the same 
                namespace as the selected interface, navigating 
                immediately to the properties tab for the new 
                interface.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                interface, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the interface from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an interface from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.interface_property_fields">

          <title>Property Fields For Interface</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the interface. The name of 
                an interface has a leading capital letter, with words 
                separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>Unlike classes, the ArgoUML critics will not 
                  complain about interface names that do not have an 
                  initial capital.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Interface is provided by 
                default with the UML standard stereotypes for the 
                parent meta-class, <literal>Classifier</literal> (
                <literal>metaclass</literal>, <literal>
                powertype</literal>, <literal>process</literal>, 
                <literal>thread</literal> and <literal>
                utility</literal>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows changing 
                the namespace for the interface. This is the package 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <para>Check box, with entries <literal>
                Abstract</literal>, <literal>Leaf</literal> and 
                <literal>Root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this interface cannot be instantiated, 
                    but must always be specialized. The name of an 
                    abstract interface is displayed in italics on the 
                    diagram.</para>

                    <caution>

                      <para>This is meaningless, since by definition an 
                      interface is an abstract entity. The UML&nbsp;1.3 
                      standard offers no clarification.</para>

                    </caution>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    interface cannot be further specialized, while 
                    <literal>Root</literal> indicates it can have no 
                    generalizations.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Visibility</literal></term>

              <listitem>

                <para>Radio box, with three entries <literal>
                public</literal>, <literal>protected</literal>, 
                <literal>private</literal> and
                <literal>package</literal>. Indicates whether 
                navigation to this end may be by: i) any classifier; 
                ii) only the source classifier and its children; or 
                iii) only by the source classifier.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any interface that 
                <emphasis>generalizes</emphasis> this interface.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized interface (i.e. 
                for which this interface is a generalization.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>AssociationEnds</literal></term>

              <listitem>

                <para>Text box. Lists any AssociationEnds (see 
                <xref linkend="s1.ref.association_end_class"/>) 
                connected to this interface.</para>

                <note>

                  <para>Associations between classes and interfaces 
                  <emphasis>must</emphasis> be navigable 
                  <emphasis>only</emphasis> from the class to the 
                  interface. ArgoUML will create associations between 
                  classes and interfaces with the correct navigability, 
                  but does not prevent the user from altering 
                  this.</para>

                </note>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Text area. Lists all the operations (see 
                <xref linkend="s1.ref.operation"/>) defined on this 
                interface. Button&nbsp;1 double click navigates to the 
                selected operation. Button&nbsp;2 click will show a popup 
                menu with two items: <literal>Move Up</literal> and 
                <literal>Move Down</literal>, which allow reordering 
                the operations.</para>

                <caution>

                  <para>All operations on an interface 
                  <emphasis>must</emphasis> be public. The ArgoUML 
                  critics will complain if this is not the case.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.abstraction">

        <title>Abstraction</title>

        <para>An abstraction is a dependency relationship joining two 
        model elements within the model at different levels of abstraction. 
        Within ArgoUML it is principally used through its specific 
        stereotype <literal>realize</literal> to define realization 
        dependencies, which link model elements that 
        <emphasis>specify</emphasis> behavior to the corresponding 
        model elements that <emphasis>implement</emphasis> the 
        behavior.</para>

        <para>In the UML metamodel <literal>Abstraction</literal> is a 
        sub-class of <literal>Dependency</literal> and through that 
        <literal>Relationship</literal>.</para>

        <para>An abstraction with stereotype <literal>realize</literal> 
        is represented on a class diagram as a dotted line with a solid 
        white head at the specifying end.</para>

        <caution>

          <para>All other stereotypes of abstraction should be 
          represented using an open arrow head, but this is not 
          supported by ArgoUML.</para>

        </caution>

        <sect2>

          <title>Abstraction Details Tabs</title>

          <para>The details tabs that are active for abstractions are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.abstraction_property_toolbar"/> 
                and <xref linkend="s2.ref.abstraction_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab. See 
                <xref linkend="s2.ref.documentation_tab"/>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>
                    The values in the "bounds" field of the 
                    abstraction
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. This contains the single 
                downlighted text <literal>N/A</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Abstraction</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    abstraction is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived abstractions still have their value 
                      in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.abstraction_property_toolbar">

          <title>Abstraction Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the abstraction from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an abstraction from the diagram, but keep it within 
                  the model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.abstraction_property_fields">

          <title>Property Fields For Abstraction</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the abstraction. There are 
                no constraints on the name of an abstraction, which is 
                not shown on any diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Abstraction is provided by 
                default with the UML standard stereotypes <literal>
                derive</literal>, <literal>realize</literal>, <literal>
                refine</literal> and <literal>trace</literal>.</para>

                <caution>

                  <para>ArgoUML automatically selects the stereotype 
                  realize when an abstraction is created. The user is 
                  free to change the stereotype to use the abstraction 
                  to indicate for example a <literal>trace</literal> 
                  relationship. However ArgoUML will not alter the 
                  representation on the diagram accordingly.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows changing 
                the namespace for the abstraction. This is the package 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Suppliers</literal></term>

              <listitem>

                <para>Text area. Lists the model element that is the 
                supplier end of this abstraction (for a realization 
                this is the end providing the implementation).</para>

                <note>

                  <para>Although this is a text area there is no 
                  mechanism for adding more than one supplier.</para>

                </note>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Clients</literal></term>

              <listitem>

                <para>Text area. Lists the model element that is the client 
                end of this abstraction (for a realization this is the 
                end providing the specification).</para>

                <note>

                  <para>Although this is a text area there is no 
                  mechanism for adding more than one client.</para>

                </note>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entseq">

      <title>Sequence Diagram Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a sequence diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>There is a close relationship between this material and 
        the <literal>Properties</literal> tab of the details pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <caution>

          <para>Sequence diagrams are not fully developed yet in 
          ArgoUML. Many aspects are not fully implemented, or may not 
          behave as expected.</para>

        </caution>

        <para><xref linkend="fig.ref.sequence_diagram"/> shows a 
        sequence diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.sequence_diagram">

          <title>Possible model elements on a sequence diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/sequence_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>Limitations Concerning Sequence Diagrams in 
          ArgoUML</title>

          <para>The sequence diagram is still rather under-developed in 
          ArgoUML.</para>

          <para>The biggest difficulties are with the actions behind 
          the stimuli. These are purely textual in implementation, and 
          there is no way to link them back to their associated 
          operations or signals.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.object_sequence">

        <title>Object</title>

        <para>An object is an instance of a class. In the UML metamodel 
        <literal>Object</literal> is a sub-class of <literal>
        Instance</literal>. Within a sequence diagram objects may be 
        used to represent a specific instance of a class. Unlike 
        collaboration diagrams (see <xref linkend="ch.ref.entcollab"/>
        ), sequence diagrams cannot show generic behavior between 
        classifier roles.</para>

        <para>An object is represented on a sequence diagram in ArgoUML 
        as a plain box labeled with the object name (if any) and class 
        name, separated by a colon (:). As links with stimuli to and 
        from other objects are added, a time line grows down from the 
        object. This is thin where the object does not have control and 
        thick where it does.</para>

        <caution>

          <para>The current release of ArgoUML shows interactions 
          between objects, although the UML standard for sequence 
          diagrams is for interaction between instances of any 
          classifier).</para>

          <para>However the actual implementation in ArgoUML permits 
          any classifier to be used with the object, and so the diagram 
          can successfully represent instances of actors for example as 
          well as classes.</para>

        </caution>

        <sect2>

          <title>Object Details Tabs</title>

          <para>The details tabs that are active for objects are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.object_property_toolbar"/> and 
                <xref linkend="s2.ref.object_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The values for the bounds of the 
                object notionally define the bounding box of the object 
                and its time line. However if you change them it will 
                have no effect, and the original values will be reset 
                when you next revisit the tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>An object should not generate any code, so 
                  having this tab active is probably a mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Object</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Instance</literal>. Showing 
                    the permanence of the state information associated 
                    with the object. Values <literal>
                    transitory</literal> (state is destroyed when the 
                    object is destroyed) and <literal>
                    persistent</literal> (state is preserved when the 
                    object is destroyed).</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the object 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived objects still have their value in 
                      analysis and design to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Classifier.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.object_property_toolbar">

          <title>Object Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                object, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the object from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an object from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.object_property_fields">

          <title>Property Fields For Object</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the object. By convention 
                object names start with a lower case letter and use 
                bumpy caps to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Object has no stereotypes by 
                default in the UML standard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype_class"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text box. Records the namespace for the object. 
                This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli Sent</literal></term>

              <listitem>

                <para>Text area. Lists the stimuli sent to this 
                object.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli Received</literal></term>

              <listitem>

                <para>Text area. Lists the stimuli received by this 
                object.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Classifier</literal></term>

              <listitem>

                <para>Drop down selector. The name of the classifier of 
                which this is an object.</para>

                <caution>

                  <para>In the current release of ArgoUML the drop down 
                  selector will include <emphasis>all</emphasis> 
                  classifiers (i.e. interfaces, actors, use cases and 
                  datatypes as well), which is what is wanted on the 
                  diagram, although it should properly be called an 
                  instance, rather than an object. In practice only 
                  instances of classes and actors make much 
                  sense.</para>

                </caution>

                <note>

                  <para>In the current release of ArgoUML the same 
                  graphical presentation is used, even if the object is 
                  actually representing an instance of an actor (when a 
                  stick-man would be more usual).</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.stimulus">

        <title>Stimulus</title>

        <para>A stimulus is a communication between two instances and 
        is generated by an action. On a sequence diagram a stimulus is 
        associated with a link&mdash;an instance of an association linking 
        two object instances. In the UML metamodel <literal>
        Stimulus</literal> is a sub-class of <literal>
        ModelElement</literal>.</para>

        <para>The link (see <xref linkend="s1.ref.link_sequence"/>) 
        associated with a stimulus is represented on a sequence diagram 
        in ArgoUML as an arrow between the time lines of the object 
        instances (or the object head in the case of stimulus create, 
        described below) labeled with the name of the action (if any), 
        and the action, separated by a colon (:). The type of line and 
        arrowhead depends on the type of action that generated the 
        stimulus:</para>

        <itemizedlist>

          <listitem>

            <para><literal>Stimulus Call</literal>. Generated by a call 
            action, itself the result of an operation of a class. Shown 
            as a solid line with a solid arrowhead to the time line of 
            the object instance receiving the stimulus.</para>

          </listitem>

          <listitem>

            <para><literal>Stimulus Create</literal>. Generated by a 
            create action for the class for which an instance is to be 
            created Shown as a solid line with a solid arrowhead to the 
            object head of the object instance being created.</para>

          </listitem>

          <listitem>

            <para><literal>Stimulus Destroy</literal>. Generated by a 
            destroy action of the originating object. Shown as a solid 
            line with an open arrowhead terminating in a diagonal cross 
            at the end of the time line of the receiving (destroyed) 
            object instance.</para>

          </listitem>

          <listitem>

            <para><literal>Stimulus Send</literal>. Generated by a send 
            action, the result of a signal raised by an operation of 
            the sending object instance and handled by the receiving 
            object instance. Shown as a solid line with half an open 
            arrowhead.</para>

          </listitem>

          <listitem>

            <para><literal>Stimulus Return</literal>. Generated by an 
            object instance that has received an earlier call stimulus 
            and is returning a result to the calling object instance. 
            Shown as a dotted line with an open arrowhead.</para>

          </listitem>

        </itemizedlist>

        <note>

          <para>ArgoUML does not allow you to create stimuli directly, 
          but instead provides tools to create stimuli of each of the 
          five types above.</para>

        </note>

        <caution>

          <para>In the current release of ArgoUML there is no way to 
          show a terminate action where an object instance destroys 
          itself. One way is to draw a destroy action that loops back 
          to the object itself, give it an action with no name and use 
          the style tab to set an invisible line, but this still leaves 
          the arrow head showing, which is unsightly. It is also 
          semantically incorrect anyway to use a destroy action to 
          represent a terminate action.</para>

        </caution>

        <sect2>

          <title>Stimulus Details Tabs</title>

          <para>The details tabs that are active for stimuli are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.stimulus_property_toolbar"/> and 
                <xref linkend="s2.ref.stimulus_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Style</literal></term>

              <listitem>

                <para>Standard tab. The values for the bounds of the 
                stimulus notionally define the bounding box of the 
                stimulus and its time line. However if you change them 
                it will have no effect, and the original values will be 
                reset when you next revisit the tab.</para>

                <para>Altering the <literal>Fill</literal> and <literal>
                Shadow</literal> entries has no effect. Rather 
                bizarrely you can set the <literal>Line</literal> entry 
                and it will draw a line around the signal, which is not 
                a standard UML representation.</para>

                <tip>

                  <para>To change the color of the line, you should 
                  select the associated link (click on it a little way 
                  from the stimulus) and use its style tab (see 
                  <xref linkend="s1.ref.link_sequence"/>).</para>

                </tip>

                <caution>

                  <para>In the current release of ArgoUML changing the 
                  values of the <literal>Bounds</literal> field is 
                  possible, but will make only a temporary change to 
                  the position of the stimulus. Selecting any model element 
                  on the screen causes the stimulus to return to its 
                  original position and the original values to be 
                  restored.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>A stimulus should not generate any code, so 
                  having this tab active is probably a mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Constraints</literal></term>

              <listitem>

                <para>Standard tab. ArgoUML only supports constraints 
                on Classes and Features (Attributes, Operations, 
                Receptions, and Methods), so this tab is grayed 
                out.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Stimulus</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    stimulus is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived stimuli still have their value in 
                      analysis and design to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.stimulus_property_toolbar">

          <title>Stimulus Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the stimulus from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an stimulus from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.stimulus_property_fields">

          <title>Property Fields For Stimulus</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. There is no convention for naming 
                stimuli, and it is quite normal to leave them unnamed. 
                The action is sufficient identification.</para>

                <tip>

                  <para>It is sometimes useful to give simple names to 
                  stimuli, so they can be referred to in attached notes 
                  giving timing constraints.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Action</literal></term>

              <listitem>

                <para>Text box. This is used to identify the action 
                that generated the stimulus.</para>

                <caution>

                  <para>The current release of ArgoUML only implements 
                  actions as textual descriptions.</para>

                  <para>As a practical convention it is suggested that 
                  call actions are shown as the name of the operation 
                  generating the action with any arguments in 
                  parentheses and that send actions are shown as the 
                  name of the signal generating the action with any 
                  arguments in parentheses. Return actions should be 
                  shown as the expression for the value they return, or 
                  empty otherwise. Create and destroy actions should be 
                  left empty, since they are implied by their 
                  representation.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Stimulus has no stereotypes 
                by default in the UML standard, but ArgoUML provides 
                the stereotypes, <literal>machine</literal>, <literal>
                organization</literal> and <literal>
                person</literal>.</para>

                <caution>

                  <para>ArgoUML also provides the stereotype <literal>
                  realize</literal> for stimuli. This appears to be an 
                  error, since this stereotype properly belongs to the 
                  <literal>Abstraction</literal> metaclass.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype_class"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Sender</literal></term>

              <listitem>

                <para>Text box. Identifies the instance which sent this 
                stimulus.</para>

                <para>Button&nbsp;1 click navigates to the sender instance, 
                button&nbsp;2 gives a pop up menu with one entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Open</literal>. Navigate to the 
                    selected sender instance.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Receiver</literal></term>

              <listitem>

                <para>Text box. Identifies the instance which receives 
                this stimulus.</para>

                <para>Button&nbsp;1 click navigates to the receiver 
                instance, button&nbsp;2 gives a pop up menu with one 
                entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Open</literal>. Navigate to the 
                    selected receiver instance.</para>

                  </listitem>

                </itemizedlist>

                <warning>

                  <para>In the current release of ArgoUML this field is 
                  broken. It always shows the entry <literal>
                  none</literal> and the pop-up menu is grayed 
                  out.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text box. Records the namespace for the stimulus. 
                This is the package hierarchy.</para>

                <para>Button&nbsp;1 click on the entry will navigate to the 
                package defining this namespace (or the model for the 
                top level namespace).</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1>

        <title>Stimulus Call</title>

        <para>This tool creates a stimulus associated with a call 
        action on the diagram, creating at the same time the associated 
        link between sender and receiving instances.</para>

        <para>All details tabs and properties are identical to to that 
        of stimulus in general (see <xref linkend="s1.ref.stimulus"/>). 
        Its graphical representation on the diagram is that of a 
        stimulus associated with a call action, i.e. a solid line with 
        a solid arrow head.</para>

        <note>

          <para>Because the current release of ArgoUML does not fully 
          implement actions, there is no enforcement of the 
          relationship to a call action.</para>

        </note>

      </sect1>

      <sect1>

        <title>Stimulus Create</title>

        <para>This tool creates a stimulus associated with a create 
        action on the diagram, creating at the same time the associated 
        link between sender and receiving instances.</para>

        <para>All details tabs and properties are identical to to that 
        of stimulus in general (see <xref linkend="s1.ref.stimulus"/>). 
        Its graphical representation on the diagram is that of a 
        stimulus associated with a create action, i.e. a solid line 
        with a solid arrow head terminating at the head of the created 
        instance.</para>

        <note>

          <para>Because the current release of ArgoUML does not fully 
          implement actions, there is no enforcement of the 
          relationship to a create action.</para>

        </note>

      </sect1>

      <sect1>

        <title>Stimulus Destroy</title>

        <para>This tool creates a stimulus associated with a destroy 
        action on the diagram, creating at the same time the associated 
        link between sender and receiving instances.</para>

        <para>All details tabs and properties are identical to to that 
        of stimulus in general (see <xref linkend="s1.ref.stimulus"/>). 
        Its graphical representation on the diagram is that of a 
        stimulus associated with a destroy action, i.e. a solid line 
        with an open arrow head terminating at a cross at the bottom of 
        the destroyed instance&apos;s time line.</para>

        <note>

          <para>Because the current release of ArgoUML does not fully 
          implement actions, there is no enforcement of the 
          relationship to a destroy action.</para>

        </note>

      </sect1>

      <sect1>

        <title>Stimulus Send</title>

        <para>This tool creates a stimulus associated with a send 
        action on the diagram, creating at the same time the associated 
        link between sender and receiving instances.</para>

        <para>All details tabs and properties are identical to to that 
        of stimulus in general (see <xref linkend="s1.ref.stimulus"/>). 
        Its graphical representation on the diagram is that of a 
        stimulus associated with a send action, i.e. a solid line with 
        half an open arrow head.</para>

        <note>

          <para>Because the current release of ArgoUML does not fully 
          implement actions, there is no enforcement of the 
          relationship to a send action.</para>

        </note>

      </sect1>

      <sect1>

        <title>Stimulus Return</title>

        <para>This tool creates a stimulus associated with a return 
        action on the diagram, creating at the same time the associated 
        link between sender and receiving instances.</para>

        <para>All details tabs and properties are identical to to that 
        of stimulus in general (see <xref linkend="s1.ref.stimulus"/>). 
        Its graphical representation on the diagram is that of a 
        stimulus associated with a return action, i.e. a dotted line 
        with an open arrow head.</para>

        <note>

          <para>Because the current release of ArgoUML does not fully 
          implement actions, there is no enforcement of the 
          relationship to a return action.</para>

        </note>

      </sect1>

      <sect1 id="s1.ref.link_sequence">

        <title>Link</title>

        <para>A link is an instance of an association. In the UML 
        metamodel <literal>Link</literal> is a sub-class of <literal>
        Instance</literal>. Within a sequence diagram links are created 
        indirectly when an associated stimulus is created.</para>

        <para>An link is represented on a sequence diagram in ArgoUML 
        as a line connecting the instances concerned. However on a 
        sequence diagram the representation is modified to reflect the 
        type of action associated with the stimulus carried on the link 
        (see <xref linkend="s1.ref.stimulus"/>).</para>

        <sect2>

          <title>Link Details Tabs</title>

          <para>The details tabs that are active for links are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See <xref linkend="s2.ref.link_property_toolbar"/>
                 and <xref linkend="s2.ref.link_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>
                <note>
                  <para>
                    The values in the "bounds" field of the 
                    link
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>
                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>A link should not generate any code, so having 
                  this tab active is probably a mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Link</literal> has the following standard tagged values 
                defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Instance</literal>. Showing 
                    the permanence of the state information associated 
                    with the link. Values <literal>transitory</literal> 
                    (state is destroyed when the link is destroyed) and 
                    <literal>persistent</literal> (state is preserved 
                    when the link is destroyed).</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the link is 
                    redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived links still have their value in 
                      analysis and design to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a Classifier.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.link_property_toolbar">

          <title>Link Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                link, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the link from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an link from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.link_property_fields">

          <title>Property Fields For Link</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the link. By convention 
                link names start with a lower case letter and use bumpy 
                caps to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Link has no stereotypes by 
                default in the UML standard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype_class"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text box. Records the namespace for the link. 
                This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Connections</literal></term>

              <listitem>

                <para>List box. Lists the connections of the link, i.e. 
                the link-ends.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the link-end.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entstate">

      <title>Statechart Diagram Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a statechart diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>There is a close relationship between this material and 
        the Properties Tab of the Details Pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        Properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <para><xref linkend="fig.ref.state_diagram"/> and 
        <xref linkend="fig.ref.state_diagram2"/> show statechart 
        diagrams with most possible model elements displayed.</para>

        <figure float="1" id="fig.ref.state_diagram">

          <title>Statechart diagram model elements 1.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/state_diagram_artifacts1.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <figure float="1" id="fig.ref.state_diagram2">

          <title>Statechart diagram model elements 2.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/build_house.png"
           format="PNG"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2 id="s2.ref.state_limitations">

          <title>Limitations Concerning Statechart Diagrams in 
          ArgoUML</title>

          <para>The statechart diagrams support the 7 action types 
          defined (CallAtion, CreateAction, DestroyAction,
          ReturnAction, SendAction, 
          TerminateAction and UninterpretedAction), 
          but there is no way to use the same action 
          more than once.
          Also, in a few cases, it is not possible to 
          set or select the related elements; 
          e.g.there is no way to select a signal for a SendAction. 
          </para>

          <para>Code generation from statechart diagrams is not 
          developed yet.</para>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.state">

        <title>State</title>

        <para>A state models a situation during which some (usually 
        implicit) invariant condition holds for the parent class. This 
        invariant may be a static situation such as an object waiting 
        for some external event to occur, or some dynamic activity 
        <quote>in progress</quote>.</para>

        <para>A state is represented on a statechart diagram in ArgoUML 
        as a rectangle with rounded corners, with a horizontal line 
        separating the name at the top from the description of the 
        behavior below. The description of the behavior includes the 
        entry and exit actions and any internal transitions.</para>

        <sect2>

          <title>State Details Tabs</title>

          <para>The details tabs that are active for states are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.state_property_toolbar"/> and 
                <xref linkend="s2.ref.state_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The values for the bounds of the 
                state define the bounding box of the state.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.state_property_toolbar">

          <title>State Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                state, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the state from the model</para>

                <note>

                  <para>This is a deletion from the model, 
                  <emphasis>not</emphasis> just the diagram. 
                  You can not just remove 
                  a state from the diagram, and keep it within the 
                  model, as is possible in other diagrams.
                  </para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.state_property_fields">

          <title>Property Fields For State</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the state. By convention 
                state names start with a lower case letter and use 
                bumpy caps to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Container</literal></term>

              <listitem>

                <para>Text box. Shows the container of the state. This 
                is the state hierarchy.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the composite state that contains this state. All 
                states are at least contained by the otherwise hidden 
                top-level state (named <quote>top</quote>) that is the 
                root of the state containment hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Entry-Action</literal></term>

              <listitem>

                <para>Text box. Shows the name of the action (if any) 
                to be executed on entry to this state.</para>

                <note>

                  <para>This field shows the name of the action, while 
                  on the diagram the expression of the action is 
                  shown.</para>

                </note>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry, button&nbsp;2 gives a pop up menu with two 
                entries:</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Entry 
                    action of a certain kind. This menu has the 
                    following submenus to select the kind of action: 
                    Call Action, Create Action, Destroy Action, Return 
                    Action, Send Action, Terminate Action, 
                    Uninterpreted Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the Entry-Action.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Exit-Action</literal></term>

              <listitem>

                <para>Text box. Shows the action (if any) to be 
                executed on exit from this state.</para>

                <para>Button&nbsp;1 click navigates to the selected action, 
                button&nbsp;2 gives a pop up menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Exit action 
                    of a certain kind. This menu has the following 
                    submenus to select the kind of action: Call Action, 
                    Create Action, Destroy Action, Return Action, Send 
                    Action, Terminate Action, Uninterpreted 
                    Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the Exit-Action.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Do-Activity</literal></term>

              <listitem>

                <para>Text box. Shows the action (if any) to be 
                executed while being in this state.</para>

                <para>Button&nbsp;1 click navigates to the selected action, 
                button&nbsp;2 gives a pop up menu with two entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Do-Activity 
                    (action) of a certain kind. This menu has the 
                    following submenus to select the kind of action: 
                    Call Action, Create Action, Destroy Action, Return 
                    Action, Send Action, Terminate Action, 
                    Uninterpreted Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the Do-Activity.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>
            
            <varlistentry>

              <term><literal>Deferrable Events</literal></term>

              <listitem>

                <para>Text box. Shows a list of events 
                that are candidates to be retained 
                by the state machine 
                if they trigger no transitions out of the
                state (not consumed).
                </para>

                <para>Button&nbsp;1 click navigates to the selected event, 
                button&nbsp;2 on an event 
                gives a pop up menu with the following entries.
                </para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Select</literal>. Allows 
                    to add already existing events 
                    to the list of deferred ones.
                    </para>

                  </listitem>

                  <listitem>

                    <para><literal>New</literal>. Add a new event 
                    of a certain kind. This menu has the 
                    following submenus to select the kind of event: 
                    Call Event, Change Event, Signal Event, Time Event.
                    </para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the event.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Incoming</literal></term>

              <listitem>

                <para>Text area. Lists all the transitions that enter 
                this state.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Outgoing</literal></term>

              <listitem>

                <para>Text area. Lists all the transitions that leave 
                this state.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                action.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Internal Transitions</literal></term>

              <listitem>

                <para>Text area. Lists all the internal transitions of 
                the state. Such transitions neither exit nor enter the 
                state, so they do not cause a state change. Which means 
                that the Entry and Exit actions are not invoked.</para>

                <note>

                  <para>This field shows the name of the transition, 
                  while on the diagram the name of the trigger is 
                  shown, separated with a <literal>/</literal> from
                  the effect script.</para>

                </note>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition, button&nbsp;2 gives a pop up menu with one 
                entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new internal 
                    transition.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.action_state">

        <title>Action</title>

        <para>An action specifies an executable statement and is an 
        abstraction of a computational procedure that can change the 
        state of the model. In the UML metamodel it is a child of 
        <literal>ModelElement</literal>. Since in the metamodel an 
        ActionSequence is itself an Action that is an aggregation of 
        other actions (i.e. the &quot;composite&quot; pattern), an 
        ActionSequence may be used anywhere an action may be.</para>

        <para>There are a number of different types of action that are 
        children of Action within the UML metamodel.</para>

        <itemizedlist>

          <listitem>

            <para><literal>CreateAction</literal>. Associated with a 
            classifier, this action creates an instance of that 
            classifier.</para>

          </listitem>

          <listitem>

            <para><literal>CallAction</literal>. Associated with an 
            operation, this action calls the given 
            operation.</para>

          </listitem>

          <listitem>

            <para><literal>ReturnAction</literal>. An action used to 
            return a result to an earlier caller.</para>

          </listitem>

          <listitem>

            <para><literal>SendAction</literal>. Associated with a 
            signal, this action causes the signal to be raised.</para>

          </listitem>

          <listitem>

            <para><literal>TerminateAction</literal>. Causes the 
            invoking object to self-destruct.</para>

          </listitem>

          <listitem>

            <para><literal>UninterpretedAction</literal>. An action 
            used to specify language-specific actions that do not 
            classify under the other types of actions.</para>

          </listitem>

          <listitem>

            <para><literal>DestroyAction</literal>. Destroys the 
            specified target object.</para>

          </listitem>

        </itemizedlist>

        <para>An action is represented on the diagram by the text of 
        its expression.</para>

        <caution>
          <para>The V0.20 release of ArgoUML only partially 
                  implements actions. As a practical convention it is 
                  suggested that call actions are shown as the name of 
                  the operation generating the action with any 
                  arguments in parentheses and that send actions are 
                  shown as the name of the signal generating the action 
                  with any arguments in parentheses. Return actions 
                  should be shown as the expression for the value they 
                  return, or empty otherwise. Create and destroy 
                  actions should shown as <literal>
                  create(&lt;target&gt;)</literal> and <literal>
                  destroy(&lt;target&gt;)</literal>. Terminate action 
                  should be shown as <literal>
                  terminate</literal>.
          </para>
        </caution>
        <sect2>

          <title>Action Details Tabs</title>

          <para>The details tabs that are active for actions are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.action_property_toolbar"/> and 
                <xref linkend="s2.ref.action_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab. 
                In the UML metamodel, <literal>
                Action</literal> has no standard 
                stereotypes defined.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Action</literal> has no standard tagged 
                value defined.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.action_property_toolbar">

          <title>Action Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the hierarchical 
                structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                action, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the Action from the model</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.action_property_fields">

          <title>Property Fields For Action</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the action. By convention 
                action names start with a lower case letter and use 
                bumpy caps to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>
            
            <varlistentry>

              <term><literal>Asynchronous</literal></term>

              <listitem>
                <para>Check box. 
                Indicates if a dispatched Stimulus is asynchronous or not.
                </para>
              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Script</literal></term>

              <listitem>
                <para>Double text box with the expression that defines the 
                action.
                This field consists of two parts, 
                the first one contains the body (script) of the expression, 
                and the second one contains the particular programming language 
                used to write the expression.
                </para>
              </listitem>

            </varlistentry>
             
            <varlistentry>

              <term><literal>Recurrence</literal></term>

              <listitem>

                <para>Double Text box. 
                An expression stating how many times the Action should be performed.
                The field consists of two parts: the first one for the expression, 
                the second one for the language it is written in.
                </para>

           </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Arguments</literal></term>

              <listitem>

                <para>Text box. 
                This is an ordered list with the arguments of the action.
                </para>
				
				<para>Button&nbsp;1 double-click on any of the arguments 
                navigates to that argument, button&nbsp;2 click brings up a 
                pop up menu with two entries.</para>

                <itemizedlist>

                  <listitem>
                    <para><literal>New</literal>. Create a 
                    new argument and navigate to it.</para>
                  </listitem>

                  <listitem>
                    <para><literal>Remove</literal>. Deletes the 
                    argument from the model.</para>
                  </listitem>

                </itemizedlist>
              </listitem>

            </varlistentry>

           <varlistentry>

              <term><literal>Instantiation (only for CreateAction)</literal></term>

              <listitem>

                <para>Text box. 
                This shows the classifier that gets instantiated by the create-action.
                </para>
				
				<para>Button&nbsp;1 double-click on the classifier 
                navigates to that argument, button&nbsp;2 click brings up a 
                pop up menu with one entry.</para>

                <itemizedlist>

                  <listitem>
                    <para><literal>Add...</literal>. 
                    This brings up a dialog box that allows 
                    selecting the one classifier that gets created.</para>
                  </listitem>

                </itemizedlist>
              </listitem>

            </varlistentry>

          </variablelist>


   
        </sect2>

      </sect1>

      <sect1 id="s1.ref.composite_state">

        <title>Composite State</title>

        <para>A composite state is a state that contains other states 
        (known as sub-states), allowing hierarchical state machines to 
        be constructed.</para>

        <para>A composite state is represented on a statechart diagram 
        in ArgoUML as a large rectangle with rounded corners, with a 
        horizontal line separating the name at the top from the 
        description of the behavior and the model of the sub-state 
        machine below. The description of the behavior includes the 
        entry, exit and do actions and any internal transitions.</para>

        <para>Sub-states are placed within a composite machine by 
        placing them entirely within the composite state. This can be 
        done at creation time, i.e. when creating the state for the 
        first time in the editing pane. Alternatively, an existing 
        state can be dragged onto a composite state.</para>

        <para>The description of a composite state is almost identical 
        to that of a state (see <xref linkend="s1.ref.state"/> and so 
        is not duplicated here. The only differences is one additional 
        tool, one missing field, 
        and one additional field, which are described as 
        follows.</para>

        <variablelist>

          <varlistentry>

            <term><guiicon><inlinemediaobject><imageobject>
            <imagedata align="center"
             fileref="images/icons/concurrent_region.gif"
             format="GIF"/></imageobject></inlinemediaobject></guiicon> 
            <literal>New Concurrent Region</literal></term>

            <listitem>

              <para>Adds a new concurrent region to the selected 
              composite state.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term>
            <literal>Deferrable Events</literal></term>

            <listitem>

              <para>This field is missing from V0.20 of ArgoUML.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>Subvertices</literal></term>

            <listitem>

              <para>Text area. Lists all the sub-states contained 
              within this composite state.</para>

              <para>Button&nbsp;1 double-click navigates to the selected 
              entry, button&nbsp;2 gives a pop up menu with two 
              entries.</para>

              <itemizedlist>

                <listitem>

                  <para><literal>New</literal>. A submenu pops up, with 
                  a selection of 7 kinds of states, which can be added 
                  to the model. The 7 kinds of states supported are: 
                  Pseudo State, Synch State, Stub State, Composite 
                  State, Simple State, Final State, Submachine 
                  State.</para>

                  <warning>

                    <para>Using this way of adding states to the model 
                    is not a good idea, since you will have to add the 
                    state to the diagram later. This can be done by 
                    selecting it in the explorer, and activating the 
                    pop-up menu, and selecting <quote>Add to 
                    Diagram</quote>. It is advisable to use the toolbar 
                    of the diagram instead.</para>

                  </warning>

                </listitem>

                <listitem>

                  <para><literal>Delete From Model</literal> Delete the 
                  selected state from the model.</para>

                </listitem>

              </itemizedlist>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect1>

      <sect1 id="s1.ref.concurrent_region">

        <title>Concurrent Region</title>

        <para>A Concurrent Region is an <quote>orthogonal 
        conjunctive</quote> component of a composite state, allowing 
        concurrency to be constructed.</para>

        <para>A concurrent region is represented on the diagram by a 
        tile of a composite state, separated from other regions by a 
        dashed line.</para>

        <para>ArgoUML currently only supports a horizontal division of 
        a concurrent composite state in regions.</para>

        <para>The description of the details panels of a concurrent 
        region is identical to that of a composite state (see 
        <xref linkend="s1.ref.composite_state"/> and so is not 
        duplicated here.</para>

      </sect1>

      <sect1 id="s1.ref.submachine_state">

        <title>Submachine State</title>

        <para>A submachine state is a syntactical convenience that 
        facilitates reuse and modularity. It is a shorthand that 
        implies a macro-like expansion by another state machine and is 
        semantically equivalent to a composite state. The state machine 
        that is inserted is called the referenced state machine while 
        the state machine that contains the submachine state is called 
        the containing state machine. The same state machine may be 
        referenced more than once in the context of a single containing 
        state machine. In effect, a submachine state represents a 
        <emphasis>call</emphasis> to a state machine 
        <emphasis>subroutine</emphasis> with one or more entry 
        and exit points. The entry and exit points are specified by 
        stub states. SubmachineState is a child of State.</para>

        <para>The submachine state is depicted as a normal state with 
        the additional <emphasis>include</emphasis>
         declaration above (and separated by a 
        line from) its internal transitions compartment. The expression 
        following the <literal>include</literal> reserved word is the 
        name of the invoked submachine.</para>

        <para>ArgoUML currently only supports a horizontal division of 
        a concurrent composite state in regions.</para>

        <para>The description of the details panels of a concurrent 
        region is almost identical to that of a composite state (see 
        <xref linkend="s1.ref.composite_state"/> and so is not 
        duplicated here. The only difference is one additional 
        field:</para>

        <variablelist>

          <varlistentry>

            <term><literal>Submachine</literal></term>

            <listitem>

              <para>Drop-down selector. Allows selecting the submachine 
              included within this composite state.</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect1>

      <sect1 id="s1.ref.stub_state">

        <title>Stub State</title>

        <para>A stub state only appears on a submachine state.</para>

        <para>A submachine state represents the invocation of a state 
        machine defined elsewhere. In the general case, an invoked 
        state machine can be entered at any of its substates or through 
        its default (initial) pseudostate. Similarly, it can be exited 
        from any substate or as a result of the invoked state machine 
        reaching its final state. The non-default entry and exits are 
        specified through <emphasis>stub states</emphasis>. In the UML 
        metamodel, StubState is a child of State.</para>

        <para>Every Stub State has a label on the diagram, which 
        corresponds to the pathname represented by the <quote>Reference 
        State</quote> attribute of the stub state.</para>

        <para>The description of the details panels of a stub state is 
        almost identical to that of a pseudo state (see 
        <xref linkend="s1.ref.pseudostate"/> and so is not duplicated 
        here. The only difference is one additional field:</para>

        <variablelist>

          <varlistentry>

            <term><literal>Reference State</literal></term>

            <listitem>

              <para>Drop-down selector. Allows entering the path name 
              of the reference state.</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect1>

      <sect1 id="s1.ref.transition_state">

        <title>Transition</title>

        <para>A transition is a directed relation between a source 
        state (any kind, e.g. composite state) and a destination state 
        (any kind, e.g. composite state). Within the UML metamodel, 
        <literal>Transition</literal> is a sub-class of <literal>
        ModelElement</literal>.</para>

        <para>A transition is represented on a statechart diagram in 
        ArgoUML as a line with arrow connecting the source to the 
        destination state. Next to this line is a string containing the 
        following three parts: The trigger event (e.g. a Call Event), 
        which may have parameters between brackets <literal>
        ()</literal>. Next follows (if any) the guard in square 
        brackets (<literal>[]</literal>). Finally, if there is an 
        effect (e.g. Call Action) defined, a slash (
        <literal>/</literal>) followed by the expression of the 
        action.</para>

        <sect2>

          <title>Transition Details Tabs</title>

          <para>The details tabs that are active for transitions are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.transition_property_toolbar"/> 
                and <xref linkend="s2.ref.transition_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. </para>
                <note>
                  <para>
                    The values in the "bounds" field of the 
                    transition
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>
                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.  In the UML metamodel, <literal>
                Transition</literal> has no stereotypes defined by default.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Transition</literal> has no standard tagged 
                values defined.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for a transition.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.transition_property_toolbar">

          <title>Transition Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up in the hierarchy to the parent state 
                machine.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                transition, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the transition from the model.</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a transition from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.transition_property_fields">

          <title>Property Fields For Transition</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the transition. By 
                convention transition names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>StateMachine</literal></term>

              <listitem>

                <para>Text box. Shows the name of the parent 
                StateMachine for the transition.</para>

                <para>Button&nbsp;1 double-click navigates to the 
                StateMachine shown.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>State</literal></term>

              <listitem>

                <para>Text box. Shows the name of the parent State in 
                case of an internal transition.</para>

                <para>Button&nbsp;1 double-click navigates to the State 
                shown.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Text box. Shows the source state for the 
                transition.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Target</literal></term>

              <listitem>

                <para>Text box. Shows the target state for the 
                transition.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Trigger</literal></term>

              <listitem>

                <para>Text box. Shows the trigger event (if any) which 
                invokes this transition.</para>

                <note>

                  <para>UML does not require there to be a trigger, 
                  e.g. when a guard is defined. In this case, 
                  the transition is taken 
                  immediately if the guard is true.</para>

                </note>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry, button&nbsp;2 gives a pop up menu with three 
                entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Select - Add...</literal>. 
                    This Add an existing trigger 
                    event. A sub-menu opens with 4 choices: Call Event, 
                    Change Event, Signal Event, Time Event.</para>

                  </listitem>

                  <listitem>

                    <para><literal>New</literal>. Add a new trigger 
                    event. A sub-menu opens with 4 choices: Call Event, 
                    Change Event, Signal Event, Time Event.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the trigger event from the model. This feature is 
                    always downlighted in the current version of 
                    ArgoUML.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Guard</literal></term>

              <listitem>

                <para>Text box. Shows the name of a guard (if any). The 
                expression of a guard must be true before this 
                transition can be taken.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry, button&nbsp;2 gives a pop up menu with one 
                entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new 
                    guard.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Effect</literal></term>

              <listitem>

                <para>Text box. Shows the action (if any) to be invoked 
                as this transition is taken.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                action, button&nbsp;2 gives a pop up menu with two 
                entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Effect 
                    (action) of a certain kind. This menu has the 
                    following submenus to select the kind of action: 
                    Call Action, Create Action, Destroy Action, Return 
                    Action, Send Action, Terminate Action, 
                    Uninterpreted Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the selected action from the model. 
                    </para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.call_event_state">

        <title>Event</title>

        <para>An event is an observable occurrence. In the UML 
        metamodel it is a child of <literal>
        ModelElement</literal>.</para>

        <para>There are a number of different types of events that are 
        children of event within the UML metamodel.</para>

        <itemizedlist>

          <listitem>

            <para><literal>CallEvent</literal>. Associated with an 
            operation of a class, this event is caused by a call to the 
            given operation. The expected effect is that the steps of 
            the operation will be executed.</para>

          </listitem>

          <listitem>

            <para><literal>SignalEvent</literal>. Associated with a 
            signal, this event is caused by the signal being 
            raised.</para>

          </listitem>

          <listitem>

            <para><literal>TimeEvent</literal>. An event cause by 
            expiration of a timing deadline.</para>

          </listitem>

          <listitem>

            <para><literal>ChangeEvent</literal>. An event caused by a 
            particular expression (of attributes and associations) 
            becoming true.</para>

          </listitem>

        </itemizedlist>

        <para>An event is represented by its name.</para>

        <sect2>

          <title>Event Details Tabs</title>

          <para>The details tabs that are active for events are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.call_event_property_toolbar"/> 
                and <xref linkend="s2.ref.call_event_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab.
                In the UML metamodel, an <literal>
                Event</literal> has the following standard 
                stereotypes defined.
                </para>
                <itemizedlist>

                  <listitem>
                    <para><literal>create</literal> (for a 
                    <literal>CallEvent</literal> only). 
                    Create is a stereotyped call event denoting 
                    that the instance receiving that event 
                    has just been created. 
                    For state machines, 
                    it triggers the initial transition 
                    at the topmost level of the state machine 
                    (and is the only kind of trigger 
                    that may be applied to an initial transition).
                    </para>
                  </listitem>

                  <listitem>
                    <para><literal>destroy</literal> (for a 
                    <literal>CallEvent</literal> only). 
                    Destroy is a stereotyped call event denoting 
                    that the instance receiving the event 
                    is being destroyed.
                    </para>
                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, an <literal>
                Event</literal> has no standard tagged 
                values defined.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.call_event_property_toolbar">

          <title>Event Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the composition structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                event, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/parameter.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New parameter</literal></term>

              <listitem>

                <para>This creates a new parameter for the event 
                operation as the current parameter, navigating 
                immediately to the properties tab for that parameter 
                (see <xref linkend="s1.ref.parameter"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the event from the model.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.call_event_property_fields">

          <title>Property Fields For Event</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the event. By convention 
                event names start with a lower case letter and use 
                bumpy caps to divide words within the name in the same 
                way as operations.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

                <tip>

                  <para>For call events it makes sense to use the name 
                  of the associated operation. For signal events it 
                  make sense to use the name of the signal, prefixed by 
                  <literal>[sig]</literal>. For time events use the 
                  time expression, prefixed by <literal>
                  [time]</literal> and for change events the change 
                  expression, prefixed by <literal>
                  [change]</literal>.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text field. Shows the namespace for the event. 
                This is the composition hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Parameters</literal></term>

              <listitem>

                <para>Text area, with entries for all the actual 
                parameter values of the event (see 
                <xref linkend="s1.ref.parameter"/>).</para>

                <para>Button&nbsp;1 double-click on any of the parameters 
                navigates to that parameter, button&nbsp;2 click brings up a 
                pop up menu with one entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New Parameter</literal>. Create a 
                    new parameter and navigate to it.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Transition</literal></term>

              <listitem>

                <para>This shows the transition caused by the 
                event.</para>

                <para>button&nbsp;1 double-click on the transition navigates 
                to that transition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Operations</literal></term>

              <listitem>

                <para>Drop-down selector. Only present for a Call 
                Event. This allows specifying the operation that causes 
                the event when called.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Signal</literal></term>

              <listitem>

                <para>Text field. Only present for a Signal 
                Event. This allows specifying the signal that causes 
                the event when called.</para>
                
                <para>Button&nbsp;1 double-click navigates to the selected 
                signal, button&nbsp;2 gives a pop up menu with two 
                entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add...</literal>. This 
                    opens a dialog box that allows selecting 
                    an already existing signal.</para>

                  </listitem>

                  <listitem>

                    <para><literal>New Signal</literal>. Creates 
                    a new Signal, and navigates to it. 
                    </para>

                  </listitem>

                </itemizedlist>


              </listitem>

            </varlistentry>
            <varlistentry>

              <term><literal>When</literal></term>

              <listitem>

                <para>Double text field. Only present for a Time 
                Event. This allows expressing the time that 
                the event is called.</para>
                
                <para>The first of the two fields is for the body of the expression, 
                and the second one for the language in which it is written.</para>

              </listitem>

            </varlistentry>
            
          </variablelist>
          
          <warning>
            <para>In ArgoUML V0.20, 
            the properties panel of a change event lacks a field to enter the 
            change expression.</para>
          </warning>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.guard_state">

        <title>Guard</title>

        <para>A guard is associated with a transition. At the time an 
        event is dispatched, the guard is evaluated, and if false, its 
        transition is disabled. In the UML metamodel, <literal>
        Guard</literal> is a child of <literal>
        ModelElement</literal>.</para>

        <para>A guard is shown on the diagram by the text of its 
        expression in square brackets (<literal>[]</literal>).</para>

        <sect2>

          <title>Guard Details Tabs</title>

          <para>The details tabs that are active for guards are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.guard_property_toolbar"/> and 
                <xref linkend="s2.ref.guard_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab, containing the stereotypes for the 
                guard. In the UML metamodel, <literal>
                Guard</literal> has no standard stereotypes
                defined.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Guard</literal> has no standard tagged 
                values defined.</para>

                  </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.guard_property_toolbar">

          <title>Guard Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                guard, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the guard from the model</para>

                <warning>

                  <para>This is a deletion from the model, 
                  <emphasis>not</emphasis> just the diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.guard_property_fields">

          <title>Property Fields For Guard</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the guard. By convention 
                guard names start with a lower case letter and use 
                bumpy caps to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Transition</literal></term>

              <listitem>

                <para>Text box, showing the transition that owns this 
                guard.</para>

                <para>Button&nbsp;1 double-click on the transition navigates 
                to that transition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Expression</literal></term>

              <listitem>

                <para>Text box. The expression that defines the 
                guard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Language</literal></term>

              <listitem>

                <para>Text box. This indicates that the expression is 
                written in a particular interpretation language with 
                which to evaluate the text.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.pseudostate">

        <title>Pseudostate</title>

        <para>A pseudostate encompasses a number of different transient 
        vertices on a state machine diagram. They are used, typically, 
        to connect multiple transitions into more complex state 
        transitions paths. For example, by combining a transition 
        entering a fork pseudostate with a set of transitions exiting 
        the fork pseudostate, we get a compound transition that leads 
        to a set of concurrent target states. Pseudostates do not have 
        the properties of a full state and serve only as a connection 
        point for transactions (but with some semantic value). Within 
        the UML metamodel, <literal>Pseudostate</literal> is a 
        sub-class of <literal>StateVertex</literal>.</para>

        <para>The representation of a pseudostate on a statechart 
        diagram in ArgoUML depends on the particular kind of 
        pseudostate: initial, deepHistory, shallowHistory, join, fork, 
        junction and choice. ArgoUML lets you place any pseudostate 
        directly by tools for the specific types of pseudostate. These 
        are described in separate sections below (see 
        <xref linkend="s1.ref.initial_state"/>, 
        <xref linkend="s1.ref.junction_state"/>, 
        <xref linkend="s1.ref.branch_state"/>, 
        <xref linkend="s1.ref.fork_state"/>, 
        <xref linkend="s1.ref.join_state"/>, 
        <xref linkend="s1.ref.shallow_history"/> and 
        <xref linkend="s1.ref.deep_history"/>).</para>

        <sect2>

          <title>Pseudostate Details Tabs</title>

          <para>The details tabs that are active for pseudostates are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.pseudostate_property_toolbar"/> 
                and <xref linkend="s2.ref.pseudostate_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab, containing the stereotypes of the 
                pseudostate. In the UML metamodel, 
                <literal>PseudoState</literal> has the no standard 
                stereotypes defined.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Pseudostate</literal> has no standard tagged 
                values defined.</para>

                  </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.pseudostate_property_toolbar">

          <title>Pseudostate Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                pseudostate, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the pseudostate from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.pseudostate_property_fields">

          <title>Property Fields For Pseudostate</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the pseudostate. By 
                convention pseudostate names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

                <tip>

                  <para>Pseudostate names are not shown on the diagram 
                  and it is not usually necessary to give them a 
                  name.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Container</literal></term>

              <listitem>

                <para>Text box. Shows the container of the pseudostate. 
                This is the state hierarchy.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the composite state that contains this state (or the 
                top-level state that is the root of the state 
                containment hierarchy).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Incoming</literal></term>

              <listitem>

                <para>Text area. Lists any incoming transitions for the 
                pseudostate.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Outgoing</literal></term>

              <listitem>

                <para>Text area. Lists any outgoing transitions for the 
                pseudostate.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.initial_state">

        <title>Initial State</title>

        <para>The initial state is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) representing a source for 
        a single transition to the <emphasis>default</emphasis> state 
        of a composite state. It is the state from which any initial 
        transition is made.</para>

        <para>As a consequence it is not permissible to have incoming 
        transitions. ArgoUML will not let you create such transitions, 
        and if you import a model that has such transitions, a critic 
        will complain.</para>

        <para>There can be at most one initial pseudostate in a 
        composite state, which must have (at most) one outgoing 
        transition.</para>

        <para>An initial state is represented on the diagram as a solid 
        disc.</para>

      </sect1>

      <sect1 id="s1.ref.final_state">

        <title>Final State</title>

        <para>If a transition reaches a final state, it implies 
        completion of the activity associated with that composite 
        state, or at the top level, of the complete state machine. In 
        the UML metamodel <literal>FinalState</literal> is a child of 
        <literal>State</literal>.</para>

        <note>

          <para>A final state is a true state (with all its 
          attributes), <emphasis>not</emphasis> a pseudostate.</para>

        </note>

        <para>Completion at the top level implies termination (i.e. 
        destruction) of the owning object instance.</para>

        <para>The representation of a final state on the diagram is a 
        circle with a small disc at its center.</para>

        <sect2>

          <title>Final State Details Tabs</title>

          <para>The details tabs that are active for final states are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.final_state_property_toolbar"/> 
                and <xref linkend="s2.ref.final_state_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab, containing the stereotypes of the 
                final state. In the UML metamodel, a <literal>
                Final State</literal> has the no standard tagged 
                values defined.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Final State</literal> has no standard tagged 
                values defined.</para>

                  </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.final_state_property_toolbar">

          <title>Final State Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                state, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the final state from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.final_state_property_fields">

          <title>Property Fields For Final State</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the final state. By 
                convention final state names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

                <tip>

                  <para>Final state names are shown on the diagram but 
                  it is not usually necessary to give them a 
                  name.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Container</literal></term>

              <listitem>

                <para>Text box. Shows the container of the final state. 
                This is the state hierarchy.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the composite state that contains this state (or the 
                top-level state that is the root of the state 
                containment hierarchy).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Entry-Action</literal></term>

              <listitem>

                <para>Text box. Shows the name of the action (if any) 
                to be executed on entry to this final state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry, button&nbsp;2 gives a pop up menu with two 
                entries:</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Entry 
                    action of a certain kind. This menu has the 
                    following 7 submenus to select the kind of action: 
                    Call Action, Create Action, Destroy Action, Return 
                    Action, Send Action, Terminate Action, 
                    Uninterpreted Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the Entry-Action.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Incoming</literal></term>

              <listitem>

                <para>Text area. Lists any incoming transitions for the 
                final state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Internal Transitions</literal></term>

              <listitem>

                <para>Text area. Lists all the internal transitions of 
                the state. Such transitions neither exit nor enter the 
                state, so they do not cause a state change. Which means 
                that the Entry and Exit actions are not invoked.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.junction_state">

        <title>Junction</title>

        <para>Junction is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) which is used to split an 
        incoming transition into multiple outgoing transition segments 
        with different guard conditions. A Junction is also called a 
        Merge or Static conditional branch. The chosen transition is 
        that whose guard is true at the time of the transition.</para>

        <para>A predefined guard denoted <literal>else</literal> may be 
        defined for at most one outgoing transition. This transition is 
        enabled if all the guards labeling the other transitions are 
        false.</para>

        <para>According the UML standard, its symbol is a small black 
        circle. Alternatively, it may be represented by a diamond shape 
        (in case of &quot;Decision&quot; for Activity diagrams). 
        ArgoUML only represents a junction on the diagram as a solid 
        (white by default) diamond, and does not support the black 
        circle symbol for a junction.</para>

      </sect1>

      <sect1 id="s1.ref.branch_state">

        <title>Choice</title>

        <para>Choice is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) which is used to split an 
        incoming transition into multiple outgoing transition segments 
        with different guard conditions. Hence, a Choice allows a 
        dynamic choice of outgoing transitions. The chosen transition 
        is that whose guard is true at the time of the transition (if 
        more than one is true, one is selected at random).</para>

        <para>A predefined guard denoted <literal>else</literal> may be 
        defined for at most one outgoing transition. This transition is 
        enabled if all the guards labeling the other transitions are 
        false.</para>

        <note>

          <para>This sort of pseudostate was formerly called a <literal>
          Branch</literal> by ArgoUML.</para>

        </note>

        <para>A choice is represented on the diagram as a small solid 
        (white by default) circle (reminiscent of a small state 
        icon).</para>

      </sect1>

      <sect1 id="s1.ref.fork_state">

        <title>Fork</title>

        <para>Fork is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) which splits a transition 
        into two or more concurrent transitions.</para>

        <caution>

          <para>The outgoing transitions should not have guards. 
          However ArgoUML will not enforce this.</para>

        </caution>

        <para>A fork is represented on the diagram as a solid (black by 
        default) horizontal bar.</para>

        <tip>

          <para>This bar can be made vertical by selecting the fork, 
          and dragging with button&nbsp;1 one of its corners.</para>

        </tip>

      </sect1>

      <sect1 id="s1.ref.join_state">

        <title>Join</title>

        <para>Join is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) which joins two or more 
        concurrent transitions into a single transition.</para>

        <caution>

          <para>The incoming transitions should not have guards. 
          However ArgoUML will not enforce this.</para>

        </caution>

        <para>A join is represented on the diagram as a solid (black by 
        default) horizontal bar.</para>

        <tip>

          <para>This bar can be made vertical by selecting the join, 
          and dragging with button&nbsp;1 one of its corners.</para>

        </tip>

      </sect1>

      <sect1 id="s1.ref.shallow_history">

        <title>Shallow History</title>

        <para>Shallow History is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) that can remember the 
        last state of its container that was active. The history 
        pseudostate points to its default state with a transition arrow 
        just like the initial pseudostate does. This transition points 
        to the substate that will become active when there is no 
        history. When the container composite state has been active 
        before (i.e., when there is history), the substate that was 
        active when the container state was exited, becomes active 
        again.</para>

        <para>When placed within a multi-level hierarchy of composite 
        states, the shallow history only remembers the history for 
        states that have the same container as the history pseudostate. 
        It does not restore substates deeper in the hierarchy then the 
        history pseudostate itself.</para>

        <para>A shallow history is represented on the diagram as a 
        circle containing the letter <literal>H</literal>.</para>

      </sect1>

      <sect1 id="s1.ref.deep_history">

        <title>Deep History</title>

        <para>Deep History is a pseudostate (see 
        <xref linkend="s1.ref.pseudostate"/>) that can remember the 
        last state of its container that was active. The history 
        pseudostate points to its default state with a transition arrow 
        just like the initial pseudostate does. This transition points 
        to the substate that will become active when there is no 
        history. When the container composite state has been active 
        before (i.e., when there is history), the substate that was 
        active when the container state was exited, becomes active 
        again.</para>

        <para>When placed within a multi-level hierarchy of composite 
        states, the deep history remembers the history for all states 
        recursively which are contained in the history pseudostate 
        container. It does restore any substates no matter how deep in 
        the hierarchy.</para>

        <para>A deep history is represented on the diagram as a circle 
        containing the symbols <literal>H*</literal>.</para>

      </sect1>

      <sect1 id="s1.ref.synch_state">

        <title>Synch State</title>

        <para>A synch state is for synchronizing concurrent regions of 
        a state machine. It is used in conjunction with forks and joins 
        to insure that one region leaves a particular state or states 
        before another region can enter a particular state or states. 
        The firing of outgoing transitions from a synch state can be 
        limited by specifying a bound on the difference between the 
        number of times outgoing and incoming transitions have fired. 
        In the UML metamodel <literal>Synch</literal> is a child of 
        <literal>StateVertex</literal>.</para>

        <para>A synch state is shown as a small circle with the upper 
        bound inside it. The bound is either a positive integer or a 
        star (&apos;*&apos;) for unlimited. Synch states are drawn on 
        the boundary between two regions when possible.</para>

        <sect2>

          <title>Synch State Details Tabs</title>

          <para>The details tabs that are active for Synch states are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.synch_state_property_toolbar"/> 
                and <xref linkend="s2.ref.synch_state_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab, containing the stereotypes of the 
                Synch state. In the UML metamodel, <literal>
                Synch State</literal> has no standard  
                stereotypes defined.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Synch State</literal> has no standard tagged 
                values defined.</para>

                  </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.synch_state_property_toolbar">

          <title>Synch State Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                synch state, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the synch state from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.synch_state_property_fields">

          <title>Property Fields For Synch State</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the Synch state. By 
                convention Synch state names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

                <tip>

                  <para>Synch state names are not shown on the diagram 
                  and it is not usually necessary to give them a 
                  name.</para>

                </tip>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Container</literal></term>

              <listitem>

                <para>Text box. Shows the container of the Synch state. 
                This is the state hierarchy.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the composite state that contains this state (or the 
                top-level state that is the root of the state 
                containment hierarchy).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Bound</literal></term>

              <listitem>

                <para>Editable text box. Shows the Bound of the Synch 
                state. Which is a positive integer or the value 
                <emphasis>unlimited</emphasis>
                (represented by a &quot;*&quot;) specifying 
                the maximal count of the SynchState. The count is the 
                difference between the number of times the incoming and 
                outgoing transitions of the synch state are 
                fired.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Incoming</literal></term>

              <listitem>

                <para>Text area. Lists any incoming transitions for the 
                final state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Outgoing Transitions</literal></term>

              <listitem>

                <para>Text area. Lists any outgoing transitions for the 
                final state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                transition.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entcollab">

      <title>Collaboration Diagram Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a collaboration diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>There is a close relationship between this material and 
        the properties tab of the details pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        Properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <caution>

          <para>Collaboration diagrams are not fully developed yet in 
          ArgoUML. Many aspects are not fully implemented, or may not 
          behave as expected. In particular there are some serious 
          problems with layout of the collaboration roles and 
          messages.</para>

        </caution>

        <para><xref linkend="fig.ref.collaboration_diagram"/> shows a 
        collaboration diagram with all possible model elements 
        displayed.</para>

        <figure float="1" id="fig.ref.collaboration_diagram">

          <title>Possible model elements on a collaboration diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/collaboration_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>Limitations Concerning Collaboration Diagrams in 
          ArgoUML</title>

          <para>The collaboration diagram is still rather 
          under-developed in ArgoUML. In particular there is no way to 
          show instance collaborations (based on objects and links) 
          rather than specification collaborations.</para>

          <para>The biggest difficulties are with the messages. There 
          are problems with the sequencing of the messages and their 
          display on the diagram. The actions behind them are purely 
          textual in implementation and there is no way to link them 
          back to their associated operations or signals.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Classifier Role</title>

        <para>A classifier role is a specialization of a classifier, 
        used to show its behavior in a particular context. In the UML 
        metamodel <literal>Classifier Role</literal> is a sub-class of 
        <literal>Classifier</literal>. Within a collaboration diagram 
        classifier roles may be used in one of two ways:</para>

        <itemizedlist>

          <listitem>

            <para>To represent the classifier in a particular 
            behavioral context (the <emphasis>specification 
            level</emphasis>); or</para>

          </listitem>

          <listitem>

            <para>to specify a particular instance of the classifier 
            (the <emphasis>instance level</emphasis>).</para>

          </listitem>

        </itemizedlist>

        <para>In this latter form, classifier roles are identical to 
        the instances used in sequence diagrams (see 
        <xref linkend="ch.ref.entseq"/>) and a collaboration diagram 
        shows the same information as the sequence diagram, but in a 
        different presentation.</para>

        <caution>

          <para>A collaboration diagram should not mix classifier roles 
          used as the specifier level and the instance level.</para>

        </caution>

        <para>A classifier role is represented on a sequence diagram in 
        ArgoUML as a plain box labeled with the classifier role name 
        (if any) and classifier, separated by a colon (:).</para>

        <caution>

          <para>A classifier role should properly also show object name 
          (if any) preceding the classifier role name and separated 
          from it by a slash (<literal>/</literal>). This allows 
          classifier roles in a specification level diagram to be 
          distinguished from instances in an instance level 
          diagram.</para>

          <para>ArgoUML does show the slash, but there is no way to 
          define the instances.</para>

        </caution>

        <sect2>

          <title>Classifier Role Details Tabs</title>

          <para>The details tabs that are active for classifier roles 
          are as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.classifier_role_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.classifier_role_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>A classifier role should not generate any code, 
                  so having this tab active is probably a 
                  mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Classifier Role</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>. Showing 
                    the permanence of the state information associated 
                    with the classifier role. Values <literal>
                    transitory</literal> (state is destroyed when the 
                    classifier role is destroyed) and <literal>
                    persistent</literal> (state is preserved when the 
                    classifier role is destroyed).</para>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    classifier role.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    classifier role is redundant&mdash;it can be formally 
                    derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <note>

                      <para>Derived classifier roles still have their 
                      value in analysis and design to introduce useful 
                      names or concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.classifier_role_property_toolbar">

          <title>Classifier Role Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New reception</literal></term>

              <listitem>

                <para>This creates a new reception, navigating 
                immediately to the properties tab for that 
                reception.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                classifier role, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the classifier role from the 
                model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an classifier role from the diagram, but keep it 
                  within the model, use the main menu <literal>Remove 
                  From Diagram</literal> (or press the Delete 
                  key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.classifier_role_property_fields">

          <title>Property Fields For Classifier Role</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the classifier role. By 
                convention classifier role names start with a lower 
                case letter and use bumpy caps to divide words within 
                the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Classifier Role is provided 
                by default with the UML standard stereotypes for a 
                classifier (<literal>metaclass</literal>, <literal>
                powertype</literal>, <literal>process</literal>, 
                <literal>thread</literal> and <literal>
                utility</literal>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text box. Records the namespace for the 
                classifier role, which is always the containing 
                Collaboration.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the collaboration.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Multiplicity</literal></term>

              <listitem>

                <para>Editable drop down selector. The default value is 
                <literal>*</literal>, which means that there are any 
                number of instances of this classifierrole that play a 
                role in the collaboration. The drop down provides some 
                different multiplicities. E.g. <literal>1..1</literal> 
                would mean that only one instance plays a role in this 
                collaboration.</para>

                <para>ArgoUML does not restrict you to the predefined 
                ranges for multiplicity. You can edit this field 
                freely.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base</literal></term>

              <listitem>

                <para>List. The names of the classifiers of which this 
                is a classifierrole. Button&nbsp;1 double click navigates to 
                the classifier. Button&nbsp;2 click gives a pop up menu with 
                the following entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. Allows adding or 
                    removeing classifiers to the list. To this end, a 
                    dialog box pops up, as shown in the figure 
                    below.</para>

                    <figure float="1" id="fig.ref.signal_add_classifierrole_base">

                      <title>The <quote>add context</quote> dialog 
                      box</title>

                      <screenshot><mediaobject><imageobject>
                      <imagedata align="center"
                       fileref="images/reference/signal_add_classifierrole_base.png"
                       format="PNG"/></imageobject></mediaobject></screenshot>
                    </figure>

                  </listitem>

                  <listitem>

                    <para><literal>Remove</literal>. Allows removeing 
                    classifiers to the list, without making use of the 
                    dialog box.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any classifierrole that 
                <emphasis>generalizes</emphasis> this 
                classifierrole.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized classifierrole 
                (i.e. for which this classifierrole is a 
                generalization).</para>

                <para>button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association End Role</literal></term>

              <listitem>

                <para>Text area. Lists the association-end roles that 
                are linked to this classifier role.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Available Contents</literal></term>

              <listitem>

                <para>Text area. Lists the subset of modelelements 
                contained in the base classifier which is used in the 
                collaboration.</para>

                <para>Button&nbsp;1 double click navigates to the 
                modelelement and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Available Features</literal></term>

              <listitem>

                <para>Text box. Lists the subset of features of the 
                base classifier which is used in the 
                collaboration.</para>

                <para>button&nbsp;1 double click navigates to the feature 
                and opens its property tab.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.association_role">

        <title>Association Role</title>

        <para>An association role is a specialization of an 
        association, used to describe an associations behavior in a 
        particular context. In the UML metamodel <literal>Association 
        Role</literal> is a sub-class of <literal>
        Association</literal>.</para>

        <para>An association role is represented on a collaboration 
        diagram in ArgoUML as a line connecting the instances 
        concerned. However on a sequence diagram the representation is 
        modified to reflect the type of action associated with the 
        stimulus carried on the link (see 
        <xref linkend="s1.ref.stimulus"/>).</para>

        <para>The association role is labeled with the association role 
        name (if any).</para>

        <para>

          An association role shows its name and the association name 
          according the following syntax:
          <blockquote>

            <para>/ AssociationRoleName : AssociationName</para>

          </blockquote>

          in the same manner as a classifier role. The more generic 
          syntax is:
          <blockquote>

            <para>I / R : C</para>

          </blockquote>

          which stands for an Instance named I originating from the 
          Classifier C playing the role R.
        </para>

        <sect2>

          <title>Association Role Details Tabs</title>

          <para>The details tabs that are active for association roles 
          are as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.association_role_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.association_role_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. </para>
                <note>
                  <para>
                    The values in the "bounds" field of the 
                    association role
                    are not editable, since they are determined 
                    by the properties of the endpoints of the line.
                  </para>
                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>An association role should not generate any 
                  code, so having this tab active is probably a 
                  mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                AssociationRole</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Association</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    association is redundant&mdash;it can be formally derived 
                    from other elements, or <literal>false</literal> 
                    meaning it cannot.</para>

                    <note>

                      <para>Derived association roles still have their 
                      value in analysis to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for an Association Role.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_role_property_toolbar">

          <title>Association Role Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the association role from the 
                model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an association role from the diagram, but keep it 
                  within the model, use the main menu <literal>Remove 
                  From Diagram</literal> (or press the Delete 
                  key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_role_property_fields">

          <title>Property Fields For Association Role</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the association role, which 
                is shown on the diagram. By convention association role 
                names start with a lower case letter and use bumpy caps 
                to divide words within the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Association role is provided 
                by default with the UML standard stereotype from the 
                superclass Association: <literal>
                implicit</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype_class"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Text box. Records the namespace for the 
                association role. This is the package hierarchy.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the item showm.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base</literal></term>

              <listitem>

                <para>Drop down selector. Records the association that 
                is the base for the association role.</para>

                <para>The drop down selector shows all associations 
                that exist between the classifiers that correspond with 
                the connected classifier roles.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Association End Roles</literal></term>

              <listitem>

                <para>Text area. Lists the ends of this association 
                role. An association role can have any number of ends, 
                but two is generally the only useful number (link 
                objects can led to a third end on instance level 
                diagrams, but this is not supported by ArgoUML). For 
                more on association end roles see 
                <xref linkend="s1.ref.association_end_role"/>.</para>

                <para>The names are listed, unless the association end 
                role has no name, then it is shown as <literal>(Unnamed 
                AssociationEndRole)</literal>.</para>

                <para>Button&nbsp;1 double click on an association end role 
                will navigate to that end.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Messages</literal></term>

              <listitem>

                <para>Text area. Lists the messages that are associated 
                with this association role.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.association_end_role">

        <title>Association End Role</title>

        <para>An association end role is a specialization of an 
        association end, used to describe an association end&apos;s 
        behavior in a particular context. In the UML metamodel <literal>
        AssociationEndRole</literal> is a sub-class of <literal>
        AssociationEnd</literal>.</para>

        <para>Two or more association end roles are associated with 
        each association role (see 
        <xref linkend="s1.ref.association_role"/>), although for 
        ArgoUML, the number of ends can only be two.</para>

        <para>The association end role has no direct access on any 
        diagram, although its stereotype, name and multiplicity is 
        shown at the relevant end of the parent association role (see 
        <xref linkend="fig.ref.collaboration_diagram"/>), and some of 
        its properties can be directly adjusted with button&nbsp;2 click. 
        Where shared or composite aggregation is selected for one 
        association end role, the opposite end is shown as a solid 
        diamond (composite aggregation) or hollow diamond (shared 
        aggregation).</para>

        <note>

          <para>ArgoUML does not currently (V0.18) support showing 
          qualifiers on the diagram, as described in the UML&nbsp;1.4 
          standard.</para>

        </note>

        <caution>

          <para>An association end role should have the same, or 
          <quote>stricter</quote> attribute values than its base 
          association end. In particular its navigability should be no 
          more general. There is as yet no critic in ArgoUML to offer 
          advice on this rule.</para>

        </caution>

        <sect2>

          <title>Association End Role Details Tabs</title>

          <para>The details tabs that are active for association end 
          roles are as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.association_end_role_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.association_end_role_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab. There is no code generated for an 
                association end role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                AssociationEndRole</literal> has the following standard 
                tagged values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the 
                    association end role is redundant&mdash;it can be 
                    formally derived from other elements, or <literal>
                    false</literal> meaning it cannot.</para>

                    <tip>

                      <para>Derived association end roles still have 
                      their value in analysis to introduce useful names 
                      or concepts, and in design to avoid 
                      re-computation. However the tag only makes sense 
                      for an association end role if it is also applied 
                      to the parent association role.</para>

                    </tip>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_end_role_property_toolbar">

          <title>Association End Role Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up to the association role to which this 
                end role belongs.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/association_end_role.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go Opposite</literal></term>

              <listitem>

                <para>This navigates to the other end of the 
                association role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/attribute.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Qualifier</literal></term>

              <listitem>

                <indexterm><primary>Add Qualifier</primary></indexterm>
                <indexterm><primary>New Qualifier</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Qualifier</secondary></indexterm>
                <para>This creates a new Qualifier for the selected 
                association-end role, navigating immediately to the 
                properties tab for that qualifier.</para>

                <warning>

                  <para>Qualifiers are only partly supported in ArgoUML 
                  V0.18. Hence, activating this button creates a 
                  qualifier in the model, which is not shown on the 
                  diagram. Also, the properties panel for a qualifier 
                  equals that of a regular attribute.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                association-end role, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the selected association-end from 
                the model.</para>

                <note>

                  <para>This button is downlighted for binary 
                  association roles, since an association needs at 
                  least <emphasis>two</emphasis> ends. Only for N-ary 
                  associations, this button is accessable, and deletes 
                  just one end from the association.</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.association_end_role_property_fields">

          <title>Property Fields For Association End Role</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the association end role, 
                which provides a <emphasis>role name</emphasis> for 
                this end of the association role. This role name can be 
                used for navigation, and in an implementation context, 
                provides a name by which the source end of an 
                association role can reference the target end.</para>

                <note>

                  <para>ArgoUML does not enforce any naming convention 
                  for association end roles.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Association end role is 
                provided by default with the UML standard stereotypes 
                for AssociationEndRole (<literal>association</literal>, 
                <literal>global</literal>, <literal>local</literal>, 
                <literal>parameter</literal>, <literal>
                self</literal>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Base</literal></term>

              <listitem>

                <para>Text field that shows the name of the 
                corresponding association end. Button&nbsp;1 double click 
                navigates to the association end.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>AssociationRole</literal></term>

              <listitem>

                <para>Text box. Records the parent association role for 
                this association end role. Button&nbsp;1 double click 
                navigates to the association role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Type</literal></term>

              <listitem>

                <para>Drop down selector providing access to all 
                standard UML types provided by ArgoUML and all new 
                classes created within the current model.</para>

                <para>This is the type of the entity attached to this 
                end of the association role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Multiplicity</literal></term>

              <listitem>

                <para>Editable drop down text entry. Allows to alter 
                the multiplicity of this association end role (with 
                respect to the other end), i.e. how many instances of 
                this end may be associated with an instance of the 
                other end. The multiplicity is shown on the diagram at 
                that end of the association role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>All remaining properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.association_end_property_fields"/>
                . Since these are completely equal to the fields of an 
                association end, they are not repeated here.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1>

        <title>Message</title>

        <para>A message is a communication between two instances of an 
        association role on a specification level collaboration 
        diagram. It describes an action which will generate the 
        stimulus associated with the message. On a collaboration 
        diagram a message is associated with an association role. In 
        the UML metamodel <literal>Message</literal> is a sub-class of 
        <literal>ModelElement</literal>.</para>

        <para>The message is represented on a collaboration diagram in 
        ArgoUML by its sequence number separated by a colon from the 
        expression defining the associated action. It is accompagnied 
        by an arrow pointing in the direction of the communication, 
        i.e. the direction of the AssociationRole. By convention the 
        name of a message is not shown on the diagram. Instead the 
        diagram displays the message sequence number, either as an 
        integer or as a decimal number to show hierarchy.</para>

        <warning>

          <para>The current release of ArgoUML does not retaining 
          message positioning after reloading the project, i.e. as if 
          the positions were not stored in the project file.</para>

        </warning>

        <sect2>

          <title>Message Details Tabs</title>

          <para>The details tabs that are active for messages are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.message_property_toolbar"/> and 
                <xref linkend="s2.ref.message_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The values for the bounds of the 
                message define the bounding box of the message. The 
                <literal>Line</literal> field defines the arrow color. 
                Increasing the <literal>Shadow</literal> size has an 
                esthetically questionable effect.</para>

                <caution>

                  <para>In the V0.18 release of ArgoUML changing the 
                  position of the message by editing the values of the 
                  <literal>Bounds</literal> field is possible, but will 
                  make only a temporary change to the position of the 
                  message, as described above.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, showing the message number and 
                action expression separated by a colon (when UML 1.4 is 
                selected in the drop-down).</para>

                <caution>

                  <para>A message probably should not generated any 
                  code of itself. That should be left to the action and 
                  possibly stimulus associated with it. In any case 
                  changes to this tab are ignored.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Message</literal> has the following standard tagged 
                values defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the message 
                    is redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived messages still have their value in 
                      analysis and design to introduce useful names or 
                      concepts, and in design to avoid 
                      re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.message_property_toolbar">

          <title>Message Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/call_action.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Action</literal></term>

              <listitem>

                <indexterm><primary>Add Action</primary></indexterm>
                <indexterm><primary>New Action</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Action</secondary></indexterm>
                <para>This creates a new Action (see 
                <xref linkend="s1.ref.action_state"/>) for the selected 
                object, navigating immediately to the properties tab 
                for that action.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                message, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the message from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an message from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.message_property_fields">

          <title>Property Fields For Message</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of a message is usually its 
                sequence number, either an integer, or a decimal 
                (allowing alternative message hierarchies to be clearly 
                described). ArgoUML will supply an integer sequence 
                number by default.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Message has no stereotypes by 
                default in the UML standard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Interaction</literal></term>

              <listitem>

                <para>Text box. Records the Interaction of which the 
                message is a part.</para>

                <para>Button&nbsp;1 double click on the entry will navigate 
                to the interaction.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Sender</literal></term>

              <listitem>

                <para>Text box. Identifies the classifier role which 
                sent this message.</para>

                <para>Button&nbsp;1 double click navigates to the sender 
                classifier role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Receiver</literal></term>

              <listitem>

                <para>Text box. Identifies the classifier role which 
                receives this message.</para>

                <para>Button&nbsp;1 double click navigates to the receiver 
                classifier role.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Activator</literal></term>

              <listitem>

                <para>Drop down selector. Identifies the message which 
                invokes the behavior that causes the sending of this 
                message.</para>

                <para>Button&nbsp;1 click allows selecting the 
                message.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Action</literal></term>

              <listitem>

                <para>Text box. Lists the action (see 
                <xref linkend="s1.ref.action_state"/>) this message 
                invokes to raise a stimulus.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                action, button&nbsp;2 gives a pop up menu with the following 
                entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new 
                    action.</para>

                    <para>This item is downlighted if an action already 
                    exists.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Predecessors</literal></term>

              <listitem>

                <para>Text area. Identifies the messages, the 
                completion of whose execution enables this 
                message.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                message, button&nbsp;2 gives a pop up menu with one 
                entry.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Add</literal>. Opens a dialog box 
                    that allows to select any number of messages. See 
                    figure below.</para>

                    <para>This entry is grayed out when no messages 
                    exist.</para>

                    <figure float="1" id="fig.ref.message_add_predecessors">

                      <title>The <quote>add predecessors</quote> dialog 
                      box</title>

                      <screenshot><mediaobject><imageobject>
                      <imagedata align="center"
                       fileref="images/reference/message_add_predecessors.png"
                       format="PNG"/></imageobject></mediaobject></screenshot>
                    </figure>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entactiv">

      <title>Activity Diagram Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within an Activity diagram. Note that some sub-model elements of 
        model elements may not actually themselves appear on the 
        diagram.</para>

        <para>There is a close relationship between this material and 
        the Properties Tab of the Details Pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        Properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <para><xref linkend="fig.ref.activity_diagram"/> shows an 
        Activity Diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.activity_diagram">

          <title>Possible model elements on an activity diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/activity_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>Limitations Concerning Activity Diagrams in 
          ArgoUML</title>

          <para>Activity diagrams are not fully developed yet in 
          ArgoUML. Some aspects are not fully implemented, or may not 
          behave as expected. In particular lacking are call states, 
          swim lanes, control icons (signals), sub-activities, synch 
          states. Interactions with other classifiers are provided by 
          an object-flow-state which is only partly implemented.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Action State</title>

        <para>An action state represents execution of an atomic action, 
        usually the invocation of an action. Within the UML metamodel, 
        <literal>ActionState</literal> is a sub-class of <literal>
        SimpleState</literal>. It is a specialized simple state that 
        only has an entry action, and with an implicit trigger as soon 
        as that action is completed.</para>

        <caution>

          <para>As a consequence any outgoing transitions from an 
          action state should not have explicit triggers defined 
          (ArgoUML will not currently check for this). They may have 
          guards to provide a choice where there is more than one 
          transition.</para>

        </caution>

        <note>

          <para>Unlike an ordinary state, an internal transition, an 
          exit action and a Do activity are not permitted for action 
          states.</para>

        </note>

        <para>An action state is represented on an activity diagram in 
        ArgoUML as a rectangle with rounded corners containing the name 
        of the action state.</para>

        <caution>

          <para>The UML standard specifies that the text shown in the 
          action state on the activity diagram should contain the 
          expression associated with the entry action - which is 
          implemented as such since ArgoUML V0.18. In past versions of 
          ArgoUML (0.16.1 and before), the diagram used to show the 
          action state name. Loading a project created by one of the 
          older versions, causes the project file to be converted to 
          the correct format to conform to the UML standard. This process is 
          designed to be transparent for the user, and the only 
          drawback is, that the activity diagram in the project will 
          not show correctly when reloaded in an old version of ArgoUML 
          again.</para>

        </caution>

        <sect2>

          <title>Action State Details Tabs</title>

          <para>The details tabs that are active for action states are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.action_state_property_toolbar"/> 
                and 
                <xref linkend="s2.ref.action_state_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The values for the bounds of the 
                action state define the bounding box of the action 
                state.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Standard tab that shows the stereotypes of the action 
                state. 
                In the UML metamodel, 
                there are no stereotypes defined 
                by default for a action state.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                ActionState</literal> has no standard tagged 
                values defined.</para>

                  </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.action_state_property_toolbar">

          <title>Action State Property ToolBar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the containment structure.
                Action states are contained by the 
                (otherwise invisible) top state.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                action state, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete from Model</literal></term>

              <listitem>

                <para>This deletes the action state from the 
                model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. It is not 
                  possible to delete an action state from the diagram, 
                  since that concept does not fit the UML 
                  standard.</para>

                  <para>Hence ArgoUML does also not show the <literal>
                  Add to Diagram</literal> pop-up menu for action 
                  states.</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.action_state_property_fields">

          <title>Property fields for action state</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the action state. By 
                convention action state names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Container</literal></term>

              <listitem>

                <para>Text box. The container of the action state.
                This shows the otherwise invisible composite state
                at the top of the containment hierarchy.
                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Entry-Action</literal></term>

              <listitem>

                <para>Text box. Shows the name of the action to be 
                invoked on entry to this action state. According the 
                UML standard, an Action State is obliged to have an 
                Entry-Action.</para>

                <para>Button&nbsp;1 double-click navigates to the shown 
                entry, button&nbsp;2 gives a pop up menu with two 
                entries.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>New</literal>. Add a new Entry 
                    action of a certain kind. This menu has the 
                    following 7 submenus to select the kind of action: 
                    Call Action, Create Action, Destroy Action, Return 
                    Action, Send Action, Terminate Action, 
                    Uninterpreted Action.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Delete From Model</literal>. Delete 
                    the Entry-Action.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>
            <varlistentry>

              <term><literal>Deferrable events</literal></term>

              <listitem>

                <para>Text box. The deferrable events of the action state. 
                <!-- This seems to be a bug. Should this be here? -->
                </para>

              </listitem>

            </varlistentry>
            
            <varlistentry>

              <term><literal>Incoming</literal></term>

              <listitem>

                <para>Text area. Lists the transitions that enter this 
                action state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Outgoing</literal></term>

              <listitem>

                <para>Text area. Lists the transitions that leave this 
                action state.</para>

                <para>Button&nbsp;1 double-click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1>

        <title>Action</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.action_state"/>).</para>

      </sect1>

      <sect1>

        <title>Transition</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.transition_state"/>).</para>

        <caution>

          <para>Remember that action states do not have explicit 
          triggers. The transition is implicitly triggered as soon as 
          the entry event of the action state is complete. An explicit 
          trigger should not therefore be set.</para>

          <para>The current release of ArgoUML will not check that this 
          constraint is met.</para>

        </caution>

        <note>

          <para>Transitions to and from an ObjectFlowState are dashed, 
          to distinguish <emphasis>object flow</emphasis> from 
          <emphasis>control flow</emphasis>.</para>

        </note>

      </sect1>

      <sect1>

        <title>Guard</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.guard_state"/>).</para>

      </sect1>

      <sect1>

        <title>Initial State</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.initial_state"/>).</para>

      </sect1>

      <sect1>

        <title>Final State</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.final_state"/>).</para>

      </sect1>

      <sect1>

        <title>Junction (Decision)</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.junction_state"/>).</para>

      </sect1>

      <sect1>

        <title>Fork</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.fork_state"/>).</para>

      </sect1>

      <sect1>

        <title>Join</title>

        <para>This model element is described in the context of statechart 
        diagrams (see <xref linkend="s1.ref.join_state"/>).</para>

      </sect1>

      <sect1>

        <title>ObjectFlowState</title>

        <para>(To Be Written)</para>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entdeploy">

      <title>Deployment Diagram Model Element Reference</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes each model element that can be created 
        within a Deployment Diagram. Note that some sub-model elements of 
        model elements on the diagram may not actually themselves appear on 
        the diagram.</para>

        <para>There is a close relationship between this material and 
        the Properties Tab of the Details Pane (see 
        <xref linkend="s1.ref.proptab"/>). That section covers 
        Properties in general, in this chapter they are linked to 
        specific model elements.</para>

        <para>Within ArgoUML, the deployment diagram is used for both 
        component diagrams (i.e. without instances, showing static 
        dependencies of components) and deployment diagrams (showing 
        how instances of components are handled by instances of nodes 
        at run-time).</para>

        <caution>

          <para>Deployment diagrams are not fully developed yet in 
          ArgoUML. Some aspects are not fully implemented or may not 
          behave as expected. Notable omissions are the possibility to 
          draw new interfaces and proper stereotyping of the various 
          dependency relationships.</para>

        </caution>

        <para><xref linkend="fig.ref.component_diagram"/> shows a 
        component diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.component_diagram">

          <title>Possible model elements on a component diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/component_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <para><xref linkend="fig.ref.deployment_diagram"/> shows a 
        deployment diagram with all possible model elements displayed.</para>

        <figure float="1" id="fig.ref.deployment_diagram">

          <title>Possible model elements on a deployment diagram.</title>

          <screenshot><mediaobject><imageobject>
          <imagedata align="center"
           fileref="images/reference/deployment_diagram.gif"
           format="GIF"/></imageobject></mediaobject></screenshot>
        </figure>

        <sect2>

          <title>Limitations Concerning Deployment Diagrams in 
          ArgoUML</title>

          <para>The deployment diagram is generally well drawn, but 
          there are only a subset of the relationships that should be 
          shown available, which restricts the ability to show dynamic 
          behavior of deployed code.</para>

          <para>It is not possible to create new interfaces directly on 
          this diagram; they can only be added if they are first 
          created in the model (by drawing them on a class 
          diagram).</para>

          <para>It is an inconvenience that the alternative 
          representation of an interface (as a small circle) is not 
          supported.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Node</title>

        <para>A node is a run-time physical object on which components 
        may be deployed. In the UML metamodel it is a sub-class of 
        <literal>Classifier</literal>.</para>

        <para>A node is represented on a class diagram as a three 
        dimensional box, labeled with its name.</para>

        <sect2>

          <title>Node Details Tabs</title>

          <para>The details tabs that are active for nodes are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See <xref linkend="s2.ref.node_property_toolbar"/>
                 and <xref linkend="s2.ref.node_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The <literal>Bounds:</literal> 
                field defines the bounding box for the node on the 
                diagram.</para>

                <warning>

                  <para>Beware that in the 0.18 release of ArgoUML, the 
                  bounding box just refers to the front face of the 
                  cube. This means that the three dimensional top and 
                  side may be ignored, for example when determining the 
                  limits of a diagram for saving graphics.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>A node should not generate any code, so having 
                  this tab active is probably a mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab. In the UML metamodel, <literal>
                Node</literal> has the following standard tagged values 
                defined.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>persistence</literal> (from the 
                    superclass, <literal>Classifier</literal>). Values 
                    <literal>transitory</literal>, indicating state is 
                    destroyed when an instance is destroyed or <literal>
                    persistent</literal>, marking state is preserved 
                    when an instance is destroyed.</para>

                  </listitem>

                  <listitem>

                    <para><literal>semantics</literal> (from the 
                    superclass, <literal>Classifier</literal>). The 
                    value is a specification of the semantics of the 
                    node.</para>

                  </listitem>

                  <listitem>

                    <para><literal>derived</literal> (from the 
                    superclass, <literal>ModelElement</literal>). 
                    Values <literal>true</literal>, meaning the node is 
                    redundant&mdash;it can be formally derived from other 
                    elements, or <literal>false</literal> meaning it 
                    cannot.</para>

                    <note>

                      <para>Derived nodes still have their value in 
                      analysis to introduce useful names or concepts, 
                      and in design to avoid re-computation.</para>

                    </note>

                  </listitem>

                </itemizedlist>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.node_property_toolbar">

          <title>Node Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New reception</literal></term>

              <listitem>

                <para>This creates a new reception, navigating 
                immediately to the properties tab for that 
                reception.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                node, navigating immediately to the properties tab for 
                that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the node from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a node from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.node_property_fields">

          <title>Property Fields For Node</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the node. The name of a 
                node has a leading capital letter, with words separated 
                by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Node is a type of classifier, 
                and so it has the default stereotypes of a classifier 
                as defined in the UML standard. ArgoUML provides the 
                standard stereotypes for a classifier: <literal>
                metaclass</literal>, <literal>powertype</literal>, 
                <literal>process</literal>, <literal>thread</literal> 
                and <literal>utility</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Allows altering the namespace 
                for the node. This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <para>Check box, with entries <literal>
                abstract</literal>, <literal>leaf</literal> and 
                <literal>root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>abstract</literal> is used to 
                    declare that this node cannot be instantiated, but 
                    must always be specialized. The name of an abstract 
                    node is displayed in italics on the diagram.</para>

                  </listitem>

                  <listitem>

                    <para><literal>leaf</literal> indicates that this 
                    node cannot be further specialized.</para>

                  </listitem>

                  <listitem>

                    <para><literal>root</literal> indicates the node 
                    can have no generalization.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text area. Lists any node that 
                <emphasis>generalizes</emphasis> this node.</para>

                <para>Button&nbsp;1 double click navigates to the 
                generalization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text box. Lists any specialized node (i.e. for 
                which this node is a generalization.</para>

                <para>Button&nbsp;1 double click navigates to the 
                specialization and opens its property tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Residents</literal></term>

              <listitem>

                <para>Text box. Lists any residents (see 
                <xref linkend="s1.ref.component"/>) designed to be 
                deployed on this type of node.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.node_instance">

        <title>Node Instance</title>

        <para>A node instance is an instance of a node where component 
        instances (see <xref linkend="s1.ref.component_instance"/>) may 
        reside. In the UML metamodel <literal>NodeInstance</literal> is 
        a sub-class of <literal>Instance</literal> and is specifically 
        an instance that is derived from a node.</para>

        <para>A node instance is represented on a deployment diagram in 
        ArgoUML as a three dimensional box labeled with the node 
        instance name (if any) and node type, separated by a colon (
        <literal>:</literal>).</para>

        <tip>

          <para>It is the presence of the colon (<literal>:</literal>) 
          and the underlining of the name and type that distinguishes a 
          node instance from a node.</para>

        </tip>

        <sect2>

          <title>Node Instance Details Tabs</title>

          <para>The details tabs that are active for node instances are 
          as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.node_instance_property_toolbar"/> 
                and 
                <xref linkend="s2.ref.node_instance_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The <literal>Bounds:</literal> 
                field defines the bounding box for the node instance on 
                the diagram.</para>

                <warning>

                  <para>Beware that in the current release of ArgoUML, 
                  the bounding box just refers to the front face of the 
                  cube. This means that the three dimensional top and 
                  side may be ignored, for example when determining the 
                  limits of a diagram for saving graphics.</para>

                </warning>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, containing just the name of the 
                node instance.</para>

                <caution>

                  <para>A node instance should not generate any code, 
                  so having this tab active is probably a 
                  mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for an Instance.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.node_instance_property_toolbar">

          <title>Node Instance Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                node instance, navigating immediately to the properties 
                tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the node instance from the 
                model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  an node instance from the diagram, but keep it within 
                  the model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.node_instance_property_fields">

          <title>Property Fields For Node Instance</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the node instance. By 
                convention node instance names start with a lower case 
                letter and use bumpy caps to divide words within the 
                name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Node instance has no 
                stereotypes by default in the UML standard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records the namespace for the 
                node instance. This is the package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli sent</literal></term>

              <listitem>

                <para>(To Be Written).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli Received</literal></term>

              <listitem>

                <para>(To Be Written).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Residents</literal></term>

              <listitem>

                <para>Text box. Lists any residents (see 
                <xref linkend="s1.ref.component"/>) designed to be 
                deployed on this type of node.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Classifiers</literal></term>

              <listitem>

                <para>Text field. A Node instance type can be selected 
                here.</para>

                <caution>

                  <para>ArgoUML V0.18 lists many more items in the 
                  dropdown list then solely Nodes. Beware to select 
                  Nodes only.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.component">

        <title>Component</title>

        <para>A component type represents a distributable piece of 
        implementation of a system, including software code (source, 
        binary, or executable) but also including business documents, 
        etc., in a human system. Components may be used to show 
        dependencies, such as compiler and run-time dependencies or 
        information dependencies in a human organization. In the UML 
        metamodel it is a sub-class of <literal>
        Classifier</literal>.</para>

        <para>A component is represented on a class diagram as a box 
        with two small rectangles protruding from its left side, 
        labeled with its name.</para>

        <sect2>

          <title>Component Details Tabs</title>

          <para>The details tabs that are active for components are as 
          follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.component_property_toolbar"/> and 
                <xref linkend="s2.ref.component_property_fields"/> 
                below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The <literal>Bounds:</literal> 
                field defines the bounding box for the component on the 
                diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, but with no contents.</para>

                <caution>

                  <para>A component should not generate any code, so 
                  having this tab active is probably a mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.component_property_toolbar">

          <title>Component Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/reception.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New reception</literal></term>

              <listitem>

                <para>This creates a new reception, navigating 
                immediately to the properties tab for that 
                reception.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                component, navigating immediately to the properties tab 
                for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the component from the model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a component from the diagram, but keep it within the 
                  model, use the main menu <literal>Remove From 
                  Diagram</literal> (or press the Delete key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.component_property_fields">

          <title>Property Fields For Component</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the component. The name of 
                a component has a leading capital letter, with words 
                separated by <quote>bumpy caps</quote>.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Component is provided by 
                default with the UML standard stereotypes <literal>
                document</literal>, <literal>executable</literal>, 
                <literal>file</literal>, <literal>library</literal> and 
                <literal>table</literal>. ArgoUML also provides the 
                standard Classifier stereotypes, <literal>
                metaclass</literal>, <literal>powertype</literal>, 
                <literal>process</literal>, <literal>thread</literal> 
                and <literal>utility</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows altering 
                the namespace for the component. This is the package 
                hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Modifiers</literal></term>

              <listitem>

                <para>Check box, with entries <literal>
                abstract</literal>, <literal>leaf</literal> and 
                <literal>root</literal>.</para>

                <itemizedlist>

                  <listitem>

                    <para><literal>Abstract</literal> is used to 
                    declare that this component cannot be instantiated, 
                    but must always be specialized.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Leaf</literal> indicates that this 
                    component cannot be further specialized.</para>

                  </listitem>

                  <listitem>

                    <para><literal>Root</literal> indicates the node 
                    can have no generalization.</para>

                  </listitem>

                </itemizedlist>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Generalizations</literal></term>

              <listitem>

                <para>Text box. Lists any component that generalizes 
                this component.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Specializations</literal></term>

              <listitem>

                <para>Text area. Lists any derived components, i.e 
                those for which this component is a 
                generalization.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Client Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists outgoing dependencies. Button&nbsp;1 
                double click navigates to the dependency.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Supplier Dependencies</literal></term>

              <listitem>

                <para>Text area. Lists incoming dependencies. Button&nbsp;1 
                double click navigates to the dependency.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Residents</literal></term>

              <listitem>

                <para>Text box. Lists any residents (see 
                <xref linkend="s1.ref.component"/>) designed to be 
                deployed on this type of node.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1 id="s1.ref.component_instance">

        <title>Component Instance</title>

        <para>A component instance is an instance of a component (see 
        <xref linkend="s1.ref.component"/>) which may reside on a node 
        instance (see <xref linkend="s1.ref.node_instance"/>). In the 
        UML metamodel <literal>ComponentInstance</literal> is a 
        sub-class of <literal>Instance</literal> and is specifically an 
        instance that is derived from a component.</para>

        <para>A component is represented on a class diagram as a box 
        with two small rectangles protruding from its left side, 
        labeled with its name.</para>

        <para>A component instance is represented on a sequence diagram 
        in ArgoUML as a box with two small rectangles protruding from 
        its left side labeled with the component instance name (if any) 
        and component type, separated by a colon (
        <literal>:</literal>).</para>

        <tip>

          <para>It is the presence of the colon (<literal>:</literal>) 
          and the underlining of the name and type that distinguishes a 
          component instance from a component.</para>

        </tip>

        <sect2>

          <title>Component Instance Details Tabs</title>

          <para>The details tabs that are active for component 
          instances are as follows.</para>

          <variablelist>

            <varlistentry>

              <term><literal>ToDoItem</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Properties</literal></term>

              <listitem>

                <para>See 
                <xref linkend="s2.ref.component_instance_property_toolbar"/>
                 and 
                <xref linkend="s2.ref.component_instance_property_fields"/>
                 below.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Documentation</literal></term>

              <listitem>

                <para>Standard tab.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Presentation</literal></term>

              <listitem>

                <para>Standard tab. The <literal>Bounds:</literal> 
                field defines the bounding box for the component on the 
                diagram.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Source</literal></term>

              <listitem>

                <para>Standard tab, containing just the name of the 
                component instance.</para>

                <caution>

                  <para>A component instance should not generate any 
                  code, so having this tab active is probably a 
                  mistake.</para>

                </caution>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Tagged Values</literal></term>

              <listitem>

                <para>Standard tab.</para>

                <note>

                  <para>The UML <literal>Element</literal> metaclass 
                  from which all other model elements are derived includes 
                  the tagged element <literal>documentation</literal> 
                  which is handled by the <emphasis>documentation 
                  tab</emphasis> under ArgoUML</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Checklist</literal></term>

              <listitem>

                <para>Standard tab for an Instance.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.component_instance_property_toolbar">

          <title>Component Instance Property Toolbar</title>

          <variablelist>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/navigate_up.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Go up</literal></term>

              <listitem>

                <para>Navigate up through the package structure.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/stereotype.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>New Stereotype</literal></term>

              <listitem>

                <indexterm><primary>Add Stereotype</primary></indexterm>
                <indexterm><primary>New Stereotype</primary></indexterm>
                <indexterm><primary>Create 
                New</primary><secondary>Stereotype</secondary></indexterm>
                <para>This creates a new Stereotype (see 
                <xref linkend="s1.ref.stereotype"/>) for the selected 
                component instance, navigating immediately to the 
                properties tab for that stereotype.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><guiicon><inlinemediaobject><imageobject>
              <imagedata align="center"
               fileref="images/icons/property_delete.gif"
               format="GIF"/></imageobject></inlinemediaobject></guiicon> 
              <literal>Delete</literal></term>

              <listitem>

                <para>This deletes the component instance from the 
                model</para>

                <warning>

                  <para>This is a deletion from the model 
                  <emphasis>not</emphasis> just the diagram. To delete 
                  a component instance from the diagram, but keep it 
                  within the model, use the main menu <literal>Remove 
                  From Diagram</literal> (or press the Delete 
                  key).</para>

                </warning>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

        <sect2 id="s2.ref.component_instance_property_fields">

          <title>Property Fields For Component Instance</title>

          <variablelist>

            <varlistentry>

              <term><literal>Name</literal></term>

              <listitem>

                <para>Text box. The name of the component instance. By 
                convention component instance names start with a lower 
                case letter and use bumpy caps to divide words within 
                the name.</para>

                <note>

                  <para>ArgoUML does not enforce this naming 
                  convention.</para>

                </note>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stereotype</literal></term>

              <listitem>

                <para>Drop down selector. Component instance has no 
                stereotypes by default in the UML standard.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Navigate Stereotype</literal></term>

              <listitem>

                <para><guiicon><inlinemediaobject><imageobject>
                <imagedata align="center"
                 fileref="images/icons/navigate_stereotype.gif"
                 format="GIF"/></imageobject></inlinemediaobject></guiicon> 
                icon. If a stereotype has been selected, this will 
                navigate to the stereotype property panel (see 
                <xref linkend="s1.ref.stereotype"/>).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Namespace</literal></term>

              <listitem>

                <para>Drop down selector. Records and allows to change 
                the namespace for the component instance. This is the 
                package hierarchy.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli sent</literal></term>

              <listitem>

                <para>(To Be Written).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Stimuli Received</literal></term>

              <listitem>

                <para>(To Be Written).</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Residents</literal></term>

              <listitem>

                <para>Text box. Lists any residents (see 
                <xref linkend="s1.ref.component"/>) designed to be 
                deployed on this component.</para>

                <para>Button&nbsp;1 double click navigates to the selected 
                entry.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>Classifiers</literal></term>

              <listitem>

                <para>Drop down selector. A Component instance type can 
                be selected here.</para>

                <caution>

                  <para>ArgoUML V0.18 lists many more items in the 
                  dropdown list then solely Components. Beware to 
                  select Components only.</para>

                </caution>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect2>

      </sect1>

      <sect1>

        <title>Dependency</title>

        <para>A key part of any component or deployment diagram is to 
        show dependencies. For details see 
        <xref linkend="s1.ref.dependency_class"/>.</para>

        <caution>

          <para>UML relies on stereotyping of dependencies on component 
          and deployment diagrams to characterize the types of 
          relationship. In the current release of ArgoUML there are 
          limitations in the implementation of dependencies which limit 
          this functionality.</para>

        </caution>

      </sect1>

      <sect1>

        <title>Class</title>

        <para>A component diagram may show the key internal structure 
        of components, including classes within the component. For 
        details see <xref linkend="s1.ref.class_class"/>.</para>

        <caution>

          <para>Classes can only be added to a component diagram if 
          they already exist in the model (by selecting them in the 
          explorer and executing the &quot;Add to diagram&quot; 
          button&nbsp;2 command). There is no way to create a new class on a 
          component diagram.</para>

        </caution>

      </sect1>

      <sect1>

        <title>Interface</title>

        <para>A component or deployment diagram may show components or 
        component instances which implement interfaces. For details see 
        <xref linkend="s1.ref.interface_class"/>.</para>

        <caution>

          <para>The V0.18 release of ArgoUML uses the same 
          representation of an interface as a class diagram. The UML 
          standard suggests that an interface on a component or 
          deployment diagram should just be shown as a small open 
          circle, connected to the component which realizes that 
          interface.</para>

        </caution>

        <warning>

          <para>There is no way to show the linking of an interface to 
          a component or component instance in the V0.18 release of 
          ArgoUML.</para>

        </warning>

      </sect1>

      <sect1>

        <title>Association</title>

        <para>Components may be associated to each other. For details 
        about associations, see 
        <xref linkend="s1.ref.association_class"/>.</para>

        <para>Where classes or interfaces are shown within components 
        on component diagrams, they may be shown linked by 
        associations.</para>

      </sect1>

      <sect1>

        <title>Object</title>

        <para>Just as components may show the classifiers that make up 
        their internal structure, component instances on deployment 
        diagrams may show the classifier instances that make up their 
        internal structure. In practice the only instance that is of 
        use is an object (an instance of a class). For details see 
        <xref linkend="s1.ref.object_sequence"/>.</para>

      </sect1>

      <sect1>

        <title>Link</title>

        <para>Where objects (Node Instances or Class Instances) are 
        shown within component instances on deployment diagrams, their 
        inter-relationships may be shown as links (instances of an 
        association). See <xref linkend="s1.ref.link_sequence"/> for 
        details.</para>

      </sect1>

    </chapter>

    <chapter id="ch.ref.entbuiltin">

      <title>Built In DataTypes, Classes, Interfaces and 
      Stereotypes</title>

      <sect1>

        <title>Introduction</title>

        <para>This chapter describes the datatypes, classes, interfaces 
        and stereotypes, which by default, are built in to 
        ArgoUML.</para>

        <para>Datatypes, classes and interfaces are generally available 
        for use anywhere a class may be selected in the properties tab. 
        The most common use is for return type and parameter types in 
        method signatures.</para>

        <sect2>

          <title>Package Structure</title>

          <para>ArgoUML datatypes, classes and interfaces are 
          effectively organized as a hierarchy beneath the overall 
          model itself. They are grouped in four packages, <literal>
          lang</literal>, <literal>math</literal>, <literal>
          net</literal> and <literal>util</literal>, themselves 
          subpackages of <literal>java</literal>, which is a subpackage 
          of the model itself. <xref linkend="fig.ref.entclasshier"/> 
          shows this structure.</para>

          <figure float="1" id="fig.ref.entclasshier">

            <title>Hierarchy of datatypes, classes and interfaces 
            within ArgoUML</title>

            <screenshot><mediaobject><imageobject>
            <imagedata align="center"
             fileref="images/reference/entclasshier.gif"
             format="GIF"/></imageobject></mediaobject></screenshot>
          </figure>

        </sect2>

        <sect2>

          <title>Exposure in the model</title>

          <para>You will not find build-in DataTypes, Classes, and 
          Interfaces exposed within the model by default (i.e. they are 
          not present in the explorer). However, once you select one of 
          the built-in DataTypes, Classes, or Interfaces (in the 
          &quot;Type&quot; combo-box on the property sheet of a 
          parameter of an operation of a class), then it becomes 
          visible: you will find that the DataType, Class, or Interface 
          has appeared in the model, in its correct package stucture 
          for the latter 2.</para>

        </sect2>

      </sect1>

      <sect1>

        <title>Built In Datatypes</title>

        <para>These are the built in atomic types. You can change them 
        if you wish. However this is not good practice.</para>

        <para>All these can be found in the <literal>
        java.lang</literal> subpackage of the main model.</para>

        <caution>

          <para>You should be aware that these are Java datatypes. They 
          are not mandated by the UML standard.</para>

        </caution>

        <para>These are the standard datatypes. For their definition 
        refer to the Java standard.</para>

        <itemizedlist>

          <listitem>

            <para><literal>boolean</literal></para>

          </listitem>

          <listitem>

            <para><literal>byte</literal></para>

          </listitem>

          <listitem>

            <para><literal>char</literal></para>

          </listitem>

          <listitem>

            <para><literal>double</literal></para>

          </listitem>

          <listitem>

            <para><literal>float</literal></para>

          </listitem>

          <listitem>

            <para><literal>int</literal></para>

          </listitem>

          <listitem>

            <para><literal>long</literal></para>

          </listitem>

          <listitem>

            <para><literal>short</literal></para>

          </listitem>

          <listitem>

            <para><literal>void</literal></para>

          </listitem>

        </itemizedlist>

        <note>

          <para><literal>void</literal> is not strictly speaking a 
          type, but the absence of type. ArgoUML knows about void and 
          allows it as an option where a datatype may be 
          selected.</para>

        </note>

      </sect1>

      <sect1>

        <title>Built In Classes</title>

        <para>These are the common classes, corresponding to classes 
        defined within the standard Java environment. It is up to you 
        if you wish to change them.</para>

        <para>These are found in all four subpackages of the <literal>
        java</literal> subpackage.</para>

        <para>For a definition of these classes see the Java language 
        and library definitions.</para>

        <sect2>

          <title>Built In Classes From <literal>
          java.lang</literal></title>

          <para>These are the classes within the <literal>
          java.lang</literal> package.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Boolean</literal></para>

            </listitem>

            <listitem>

              <para><literal>Byte</literal></para>

            </listitem>

            <listitem>

              <para><literal>Char</literal></para>

            </listitem>

            <listitem>

              <para><literal>Double</literal></para>

            </listitem>

            <listitem>

              <para><literal>Float</literal></para>

            </listitem>

            <listitem>

              <para><literal>Integer</literal></para>

            </listitem>

            <listitem>

              <para><literal>Long</literal></para>

            </listitem>

            <listitem>

              <para><literal>Object</literal></para>

            </listitem>

            <listitem>

              <para><literal>Short</literal></para>

            </listitem>

            <listitem>

              <para><literal>String</literal></para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Built In Classes From <literal>
          java.math</literal></title>

          <para>These are the classes within the <literal>
          java.math</literal> package.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Big Decimal</literal></para>

            </listitem>

            <listitem>

              <para><literal>Big Integer</literal></para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Built In Classes From <literal>
          java.net</literal></title>

          <para>These are the classes within the <literal>
          java.net</literal> package.</para>

          <itemizedlist>

            <listitem>

              <para><literal>URL</literal></para>

            </listitem>

          </itemizedlist>

        </sect2>

        <sect2>

          <title>Built In Classes From <literal>
          java.util</literal></title>

          <para>These are the classes within the <literal>
          java.util</literal> package.</para>

          <itemizedlist>

            <listitem>

              <para><literal>Vector</literal></para>

            </listitem>

            <listitem>

              <para><literal>Date</literal></para>

            </listitem>

            <listitem>

              <para><literal>Time</literal></para>

            </listitem>

          </itemizedlist>

        </sect2>

      </sect1>

      <sect1>

        <title>Built In Interfaces</title>

        <para>These are some useful interfaces, corresponding to 
        classes defined within the standard Java environment. 
        Interfaces have many of the properties of classes (like all 
        types) and you can change them if you wish.</para>

        <para>All these can be found in the <literal>
        java.util</literal> subpackage of the main model.</para>

        <para>These are the interfaces defined within the <literal>
        java.util</literal> package. For their definition consult the 
        Java language and library references.</para>

        <itemizedlist>

          <listitem>

            <para><literal>Collection</literal></para>

          </listitem>

          <listitem>

            <para><literal>Iterator</literal></para>

          </listitem>

          <listitem>

            <para><literal>List</literal></para>

          </listitem>

          <listitem>

            <para><literal>Set</literal></para>

          </listitem>

          <listitem>

            <para><literal>Sorted Set</literal></para>

          </listitem>

        </itemizedlist>

      </sect1>

      <sect1>

        <title>Built In Stereotypes</title>

        <para>UML 1.4 defines a large number of stereotypes 
        of which most are 
        supported by ArgoUML.</para>

        <caution>

          <para>Not all stereotypes defined by UML&nbsp;1.4 appear in 
          ArgoUML V0.20 due to 
          the fact that they were not yet updated 
          from previous versions of ArgoUML 
          that only supported UML 1.3.
          Also, there are
          limitations in the current implementation of 
          some base elements. The table below lists all stereotypes defined 
          in UML 1.4 and if they are supported in 
          ArgoUML or not.</para>

        </caution>

        <caution>

          <para>The UML&nbsp;1.4 standard also specifies many stereotypes in 
          the chapters <quote>Example Profiles</quote>: one for 
          <quote>Software Development</quote> and one for 
          <quote>Business Modeling</quote>. Due to the specialized 
          nature of these profiles, implementation in ArgoUML is 
          postponed until a yet undetermined moment.</para>

        </caution>

        <table frame="all">

          <title>Stereotypes defined in UML 1.4 and ArgoUML</title>

          <tgroup cols="3">

            <thead>

              <row><entry><para><emphasis>StereoType</emphasis></para></entry><entry><para><emphasis>Base 
              Element</emphasis></para></entry><entry><para><emphasis>ArgoUML 
              support</emphasis></para></entry></row>

            </thead>

            <tbody>

              <row><entry><para>access</para></entry><entry><para>Permission</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>appliedProfile</para></entry><entry><para>Package</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>association</para></entry><entry><para>AssociationEnd</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>auxiliary</para></entry><entry><para>Class</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>become</para></entry><entry><para>Flow</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>call</para></entry><entry><para>Usage</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>copy</para></entry><entry><para>Flow</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>create</para></entry><entry><para>BehavioralFeature</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>create</para></entry><entry><para>CallEvent</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>create</para></entry><entry><para>Usage</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>derive</para></entry><entry><para>Abstraction</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>destroy</para></entry><entry><para>BehavioralFeature</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>destroy</para></entry><entry><para>CallEvent</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>document</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>executable</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>facade</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>file</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>focus</para></entry><entry><para>Class</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>framework</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>friend</para></entry><entry><para>Permission</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>global</para></entry><entry><para>AssociationEnd</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>implementation</para></entry><entry><para>Class</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>implementation</para></entry><entry><para>Generalization</para></entry><entry><para>yes</para></entry></row>

              
              <row><entry><para>implicit</para></entry><entry><para>Association</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>import</para></entry><entry><para>Permission</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>instantiate</para></entry><entry><para>Usage</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>invariant</para></entry><entry><para>Constraint</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>library</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>local</para></entry><entry><para>AssociationEnd</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>metaclass</para></entry><entry><para>Class</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>metamodel</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>modelLibrary</para></entry><entry><para>Package</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>parameter</para></entry><entry><para>AssociationEnd</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>postcondition</para></entry><entry><para>Constraint</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>powertype</para></entry><entry><para>Class</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>precondition</para></entry><entry><para>Constraint</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>process</para></entry><entry><para>Classifier</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>profile</para></entry><entry><para>Package</para></entry><entry><para>no</para></entry></row>
              
              <row><entry><para>realize</para></entry><entry><para>Abstraction</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>refine</para></entry><entry><para>Abstraction</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>requirement</para></entry><entry><para>Comment</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>responsibility</para></entry><entry><para>Comment</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>self</para></entry><entry><para>AssociationEnd</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>send</para></entry><entry><para>Usage</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>signalflow</para></entry><entry><para>ObjectFlowState</para></entry><entry><para>yes</para></entry></row>
              <row><entry><para>source</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>
              <row><entry><para>stateInvariant</para></entry><entry><para>Constraint</para></entry><entry><para>no</para></entry></row>
              
              <row><entry><para>stub</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>systemModel</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>table</para></entry><entry><para>Abstraction</para></entry><entry><para>no</para></entry></row>

              <row><entry><para>thread</para></entry><entry><para>Classifier</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>topLevel</para></entry><entry><para>Package</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>trace</para></entry><entry><para>Abstraction</para></entry><entry><para>yes</para></entry></row>

              <row><entry><para>type</para></entry><entry><para>Class</para></entry><entry><para>yes</para></entry></row>


            </tbody>

          </tgroup>

        </table>

      </sect1>

    </chapter>

  </part>

  <glossary id="glossary">

    <title>Glossary</title>

    <glossdiv>

      <title>A</title>

      <glossentry id="gl.activitydiag">

        <glossterm>Activity Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Activity Diagram</primary></indexterm>
          <indexterm>
          <primary>Diagram</primary><secondary>Activity</secondary></indexterm>
          <para>A UML diagram capturing the dynamic behavior of a 
          system or sub-system. See 
          <xref linkend="s1.umlactivitydiags"/> for more 
          information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.action">

        <glossterm>Action</glossterm>

        <glossdef>

          <indexterm><primary>Action</primary></indexterm>
          <para>Behavior associated with <emphasis>States</emphasis> or 
          <emphasis>Transitions</emphasis> in <emphasis>State 
          Diagram</emphasis>. These actions are invocations of 
          <emphasis>Methods</emphasis> and appear on 
          <emphasis>Sequence</emphasis> and <emphasis>Collaboration 
          Diagrams</emphasis>.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.actor">

        <glossterm>Actor</glossterm>

        <glossdef>

          <indexterm><primary>Actor</primary></indexterm>
          <para>A representation of an agent (animate or inanimate) on 
          a <emphasis>Use Case Diagram</emphasis> external to the 
          system being designed.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.analysis">

        <glossterm>Analysis</glossterm>

        <glossdef>

          <indexterm><primary>Analysis</primary></indexterm>
          <para>Analysis is the process of taking the 
          <quote>customer</quote> requirements and re-casting them in 
          the language of, and from the perspective of, a putative 
          solution.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.assocclass">

        <glossterm>Association Class</glossterm>

        <glossdef>

          <indexterm><primary>Association Class</primary></indexterm>
          <para>A class that characterizes the association between two 
          other classes.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.association">

        <glossterm>Association</glossterm>

        <glossdef>

          <indexterm><primary>Association</primary></indexterm>
          <para>A relationship between two classes in a Class Diagram 
          or between Use Cases or Use Cases and Actors in a Use Case 
          Diagram.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.attribute">

        <glossterm>Attribute (of a Class or Object)</glossterm>

        <glossdef>

          <indexterm><primary>Attribute</primary><secondary>of a 
          Class</secondary></indexterm>
          <indexterm><primary>Attribute</primary><secondary>of an 
          Object</secondary></indexterm>
          <para>An attribute of a class or object is a specification of 
          a data element encapsulated by that object.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>C</title>

      <glossentry id="gl.case">

        <glossterm>CASE</glossterm>

        <glossdef>

          <indexterm><primary>CASE</primary></indexterm>
          <para>Computer Aided Software Engineering.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.class">

        <glossterm>Class</glossterm>

        <glossdef>

          <indexterm><primary>Class</primary></indexterm>
          <para>The encapsulation of the data associated with a 
          model element (its <emphasis>attributes</emphasis>) and the 
          actions associated with the model element (its 
          <emphasis>methods</emphasis>).</para>

          <para>A class specifies the characteristics of a model element. 
          An <emphasis>object</emphasis> represents an instance of the 
          model element.</para>

          <para>Classes and objects in UML are represented on 
          <emphasis>Activity Diagrams</emphasis>, <emphasis>Class 
          Diagrams</emphasis>, <emphasis>Collaboration 
          Diagrams</emphasis> and <emphasis>Sequence 
          Diagrams</emphasis>.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.classdiag">

        <glossterm>Class Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Class Diagram</primary></indexterm>
          <indexterm>
          <primary>Diagram</primary><secondary>Class</secondary></indexterm>
          <para>A UML Diagram showing the structural relationship 
          between classes. See <xref linkend="s1.umlclassdiags"/> for 
          more information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.collaboration">

        <glossterm>Collaboration</glossterm>

        <glossdef>

          <indexterm><primary>Collaboration</primary></indexterm>
          <para>
            The process whereby several objects cooperate to provide some
            higher level behavior that is greater than the sum of the
            behaviors of the objects.
          </para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.collabdiag">

        <glossterm>Collaboration Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Collaboration 
          Diagram</primary></indexterm>
          <indexterm>
          <primary>Diagram</primary><secondary>Collaboration</secondary></indexterm>
          <para>A UML Diagram showing the dynamic behavior as messages 
          are passed between objects. Equivalent to a 
          <emphasis>Sequence Diagram</emphasis>. Which representation 
          is appropriate depends on the problem under 
          consideration.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.collaborator">

        <glossterm>Collaborator</glossterm>

        <glossdef>

          <indexterm><primary>Collaborator</primary></indexterm>
          <para>
            An object that participates in a Collaboration.
          </para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.comprehension">

        <glossterm>Comprehension and Problem Solving</glossterm>

        <glossdef>

          <indexterm><primary>Comprehension</primary></indexterm>
          <indexterm><primary>Problem Solving</primary></indexterm>
          <para>A design visualization theory within cognitive 
          psychology. The theory notes that designers must bridge a gap 
          between their mental model of the problem or situation and 
          the formal model of a solution or system.</para>

          <para>This theory suggests that programmers will benefit 
          from:</para>

          <orderedlist>

            <listitem>

              <para>Multiple representations such as program syntactic 
              decomposition, state transitions, control flow, and data 
              flow. These allow the programmer to better identify 
              elements and relationships in the problem and solution 
              and thus more readily create a mapping between their 
              situation models and working system models.</para>

            </listitem>

            <listitem>

              <para>Familiar aspects of a situation model, which 
              improve designers&apos; abilities to formulate 
              solutions.</para>

            </listitem>

          </orderedlist>

        </glossdef>

      </glossentry>

      <glossentry id="gl.conceptclassdiag">

        <glossterm>Concept Class Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Concept Class 
          Diagram</primary></indexterm>
          <para>A Class Diagram constructed during the Analysis Phase 
          to show the main structural components of the problem 
          identified in the Requirements Phase. See 
          <xref linkend="ch.tut.analysis"/> for more information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.critic">

        <glossterm>Critic</glossterm>

        <glossdef>

          <indexterm><primary>Critic</primary></indexterm>
          <para>A process within ArgoUML that provides suggestions as 
          to how the design might be improved. Suggestions are based on 
          principles within three theories of cognitive psychology, 
          <emphasis>reflection-in action</emphasis>, 
          <emphasis>opportunistic design</emphasis> and 
          <emphasis>comprehension and problem solving</emphasis>.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>E</title>

      <glossentry id="gl.extends">

        <glossterm>Extend Relationship</glossterm>

        <glossdef>

          <indexterm><primary>Extend Relationship</primary></indexterm>
          <indexterm>
          <primary>Relationship</primary><secondary>Extend</secondary></indexterm>
          <para>A relationship between two Use Cases, where the 
          <emphasis>extended</emphasis> Use Case describes a special 
          variant of the <emphasis>extending</emphasis> Use Case.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>G</title>

      <glossentry id="gl.generalization">

        <glossterm>Generalization Relationship</glossterm>

        <glossdef>

          <indexterm><primary>Generalization 
          Relationship</primary></indexterm>
          <indexterm>
          <primary>Relationship</primary><secondary>Generalization</secondary></indexterm>
          <para>A relationship between one 
          <emphasis>generalizing</emphasis> Use Cases and one or more 
          <emphasis>generalized</emphasis> Use Cases, where the 
          <emphasis>generalized</emphasis> Use Cases are particular 
          examples of the <emphasis>generalizing</emphasis> Use 
          Case.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.gui">

        <glossterm>GUI</glossterm>

        <glossdef>

          <indexterm><primary>GUI</primary></indexterm>
          <para>Graphical User Interface.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>H</title>

      <glossentry id="gl.hierstatediag">

        <glossterm>Hierarchical Statechart Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Hierarchical Statechart 
          Diagram</primary></indexterm>
          <indexterm><primary>Statechart Diagram, 
          Hierarchical</primary></indexterm>
          <para>A <emphasis>Statechart Diagram</emphasis> that contains 
          subsidiary statechart diagrams within individual 
          <emphasis>States</emphasis>.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>I</title>

      <glossentry id="gl.includes">

        <glossterm>Include Relationship</glossterm>

        <glossdef>

          <indexterm><primary>Include Relationship</primary></indexterm>
          <indexterm>
          <primary>Relationship</primary><secondary>Include</secondary></indexterm>
          <para>A relationship between two Use Cases, where the 
          <emphasis>included</emphasis> Use Case describes part of the 
          functionality of the <emphasis>including</emphasis> Use 
          Case.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.iterative">

        <glossterm>Iterative Design Process</glossterm>

        <glossdef>

          <indexterm><primary>Iterative Design 
          Process</primary></indexterm>
          <indexterm><primary>Design 
          Process</primary><secondary>Iterative</secondary></indexterm>
          <para>A design process where each all phases (requirements, 
          analysis, design, build, test) are tackled partially in a 
          series of iterations. See <xref linkend="s2.proctypes"/> for 
          more information.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>J</title>

      <glossentry id="gl.java">

        <glossterm>Java</glossterm>

        <glossdef>

          <indexterm><primary>Java</primary></indexterm>
          <para>A fully object oriented programming language introduced 
          by Sun Microsystems. More strongly typed than C++, it 
          compiles to an interpreted code, the Java Virtual Machine 
          (JVM). The JVM means that Java code should run on any machine 
          that has implemented the JVM.</para>

          <para>The most significant component of Java was integration 
          of the JVM into web browsers, allowing code (Applets) to be 
          download and run over the web.</para>

          <para>ArgoUML is written in Java.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>M</title>

      <glossentry id="gl.mealy">

        <glossterm>Mealy Machine</glossterm>

        <glossdef>

          <indexterm><primary>Mealy Machine</primary></indexterm>
          <para>A <emphasis>Statechart Diagram</emphasis> where actions 
          are associated with <emphasis>States</emphasis>.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.method">

        <glossterm>Method (of a Class or Object)</glossterm>

        <glossdef>

          <indexterm><primary>Method</primary><secondary>of a 
          Class</secondary></indexterm>
          <indexterm><primary>Method</primary><secondary>of an 
          Object</secondary></indexterm>
          <indexterm><primary>Class Method</primary></indexterm>
          <indexterm><primary>Object Method</primary></indexterm>
          <para>A method of a class or object is a specification of 
          behavior encapsulated by that object.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.moore">

        <glossterm>Moore Machine</glossterm>

        <glossdef>

          <indexterm><primary>Moore Machine</primary></indexterm>
          <para>A <emphasis>Statechart Diagram</emphasis> where actions 
          are associated with <emphasis>Transitions</emphasis>.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>O</title>

      <glossentry id="gl.object">

        <glossterm>Object</glossterm>

        <glossdef>

          <indexterm><primary>Object</primary></indexterm>
          <para>An instance of a <emphasis>Class</emphasis>.</para>

          <para>Classes and objects in UML are represented on 
          <emphasis>Activity Diagrams</emphasis>, <emphasis>Class 
          Diagrams</emphasis>, <emphasis>Collaboration 
          Diagrams</emphasis> and <emphasis>Sequence 
          Diagrams</emphasis>.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.ocl">

        <glossterm>OCL</glossterm>

        <glossdef>

          <indexterm><primary>OCL</primary></indexterm>
          <indexterm><primary>Object Constraint 
          Language</primary></indexterm>
          <para>Object Constraint Language. A language for describing 
          constraints within UML.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.omg">

        <glossterm>OMG</glossterm>

        <glossdef>

          <indexterm><primary>OMG</primary></indexterm>
          <indexterm><primary>Object Management 
          Group</primary></indexterm>
          <para>The Object Management Group. An international industry 
          standardization body. Best known for CORBA and UML.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.ooad">

        <glossterm>OOA&amp;D</glossterm>

        <glossdef>

          <indexterm><primary>OOA&amp;D</primary></indexterm>
          <indexterm><primary>Design</primary><secondary>Object 
          Oriented</secondary></indexterm>
          <indexterm><primary>Analysis</primary><secondary>Object 
          Oriented</secondary></indexterm>
          <para>Object Oriented Analysis and Design. An approach to 
          software problem analysis and design based on objects, which 
          encapsulate both data and code. See See 
          <xref linkend="s2.ooad"/> or any standard textbook on 
          Software Engineering.</para>

          <para>UML is a notation to support OOA&amp;D.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.oppdesign">

        <glossterm>Opportunistic Design</glossterm>

        <glossdef>

          <indexterm><primary>Opportunistic Design</primary></indexterm>
          <indexterm>
          <primary>Design</primary><secondary>Opportunistic</secondary></indexterm>
          <para>A theory within cognitive psychology suggesting that 
          although designers plan and describe their work in an 
          ordered, hierarchical fashion, in actuality, they choose 
          successive tasks based on the criteria of cognitive cost. 
          Simply stated, designers do not follow even their own plans 
          in order, but choose steps that are mentally least expensive 
          among alternatives.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>P</title>

      <glossentry id="gl.pane">

        <glossterm>Pane</glossterm>

        <glossdef>

          <indexterm><primary>Pane</primary></indexterm>
          <para>A sub-window within the main window of the ArgoUML user 
          interface.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>R</title>

      <glossentry id="gl.relusecase">

        <glossterm>Realization Use Case</glossterm>

        <glossdef>

          <indexterm><primary>Realization Use Case</primary></indexterm>
          <indexterm><primary>Use Case Realization</primary></indexterm>
          <para>A <emphasis>Use Case</emphasis> where the <emphasis>Use 
          Case Diagram</emphasis> and <emphasis>Use Case 
          Specification</emphasis> are in the language of the solution 
          domain, rather than the problem domain.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.reflection">

        <glossterm>Reflection-in-Action</glossterm>

        <glossdef>

          <indexterm><primary>Reflection-in-Action</primary></indexterm>
          <para>A theory within cognitive psychology which observes 
          that designers of complex systems do not conceive a design 
          fully-formed. Instead, they must construct a partial design, 
          evaluate, reflect on, and revise it, until they are ready to 
          extend it further. As developers work hands-on with the 
          design, their mental model of the problem situation improves, 
          hence improving their design.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.requirements">

        <glossterm>Requirement Capturing</glossterm>

        <glossdef>

          <indexterm><primary>Requirement 
          Capturing</primary></indexterm>
          <para>Requirement capturing is the process of identifying 
          what the <quote>customer</quote> wants from the proposed 
          system. See <xref linkend="ch.tut.reqs"/> for a fuller 
          description.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.responsibility">

        <glossterm>Responsibility</glossterm>

        <glossdef>

          <indexterm><primary>Responsibility</primary></indexterm>
          <para>S
            ome behavior for which an object is held accountable.
            A responsibility denotes the obligation of an object to provide a
            certain behavior.
          </para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>S</title>

      <glossentry id="gl.scenario">

        <glossterm>Scenario</glossterm>

        <glossdef>

          <indexterm><primary>Scenario</primary></indexterm>
          <para>
            A specific sequence of actions that illustrates behavior.
          </para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.seqdiag">

        <glossterm>Sequence Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Sequence Diagram</primary></indexterm>
          <indexterm>
          <primary>Diagram</primary><secondary>Sequence</secondary></indexterm>
          <para>A UML Diagram showing the dynamic behavior as messages 
          are passed between objects. Equivalent to a 
          <emphasis>Collaboration Diagram</emphasis>. Which 
          representation is appropriate depends on the problem under 
          consideration. See <xref linkend="s1.umlseqdiags"/> for more 
          information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.sgml">

        <glossterm>SGML</glossterm>

        <glossdef>

          <indexterm><primary>SGML</primary></indexterm>
          <indexterm><primary>Standard Graphical Markup 
          Language</primary></indexterm>
          <para>Standard Graphical Markup Language. Defined by ISO 
          8879:1986.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.simula67">

        <glossterm>Simula&nbsp;67</glossterm>

        <glossdef>

          <indexterm><primary>Simula&nbsp;67</primary></indexterm>
          <para>A procedural programming language intended for 
          simulation. Noted for its introduction of 
          <emphasis>objects</emphasis> and 
          <emphasis>coroutines</emphasis>.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.state">

        <glossterm>State</glossterm>

        <glossdef>

          <indexterm><primary>State</primary></indexterm>
          <para>Within a <emphasis>Statechart Diagram</emphasis> a one 
          of the possible configurations of the machine.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.statediag">

        <glossterm>Statechart Diagram</glossterm>

        <glossdef>

          <indexterm><primary>State Diagram</primary></indexterm>
          <indexterm><primary>Statechart Diagram</primary></indexterm>
          <indexterm>
          <primary>Diagram</primary><secondary>State</secondary></indexterm>
          <para>A UML Diagram showing the dynamic behavior of an active 
          <emphasis>Object</emphasis>. See 
          <xref linkend="s1.umlstatediags"/> for more 
          information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.stereotype">

        <glossterm>Stereotypes and Stereotyping</glossterm>

        <glossdef>

          <indexterm><primary>Stereotype</primary></indexterm>
          <indexterm><primary>Stereotyping</primary></indexterm>
          <para>Any model element within UML can be given a 
          <emphasis>stereotype</emphasis> to indicate its association 
          with a particular role in the design. A stereotype <literal>
          spqr</literal> is generally indicated with the notation 
          <literal>&lt;&lt;spqr&gt;&gt;</literal>.</para>

          <para>A stereotype defines a Namespace within the design. 
          Examples of stereotypes are <literal>
          &lt;&lt;business&gt;&gt;</literal> and <literal>
          &lt;&lt;realization&gt;&gt;</literal> for Use Cases, used to 
          distinguish between Use Cases at the requirements phase 
          defined in terms of the problem domain, and Use Cases at the 
          analysis phase defined in terms of the solution domain.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.supspec">

        <glossterm>Supplementary Requirement Specification</glossterm>

        <glossdef>

          <indexterm><primary>Supplementary Requirement 
          Specification</primary></indexterm>
          <para>The document capturing non-functional requirements that 
          cannot be associated with Use Cases.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.svg">

        <glossterm>SVG</glossterm>

        <glossdef>

          <indexterm><primary>SVG</primary></indexterm>
          <para>Scalable Vector Graphics format. A standard 
          representation of graphics diagrams that use vectors. ArgoUML 
          can export diagrams in SVG.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.sysseqdiag">

        <glossterm>System Sequence Diagram</glossterm>

        <glossdef>

          <indexterm><primary>System Sequence 
          Diagram</primary></indexterm>
          <indexterm><primary>Diagram</primary><secondary>System 
          Sequence</secondary></indexterm>
          <para>A <emphasis>Sequence Diagram</emphasis> used in the 
          <emphasis>Analysis</emphasis> Phase showing the dynamic 
          behavior of the overall system. See 
          <xref linkend="ch.tut.analysis"/> for more information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.sysstatediag">

        <glossterm>System Statechart Diagram</glossterm>

        <glossdef>

          <indexterm><primary>System Statechart 
          Diagram</primary></indexterm>
          <indexterm><primary>Diagram</primary><secondary>System 
          State</secondary></indexterm>
          <para>A <emphasis>Statechart Diagram</emphasis> used in the 
          <emphasis>Analysis</emphasis> Phase showing the dynamic 
          behavior of an active top level system objects. See 
          <xref linkend="ch.tut.analysis"/> for more information.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>T</title>

      <glossentry id="gl.todo">

        <glossterm>To-Do List</glossterm>

        <glossdef>

          <indexterm><primary>To-Do List</primary></indexterm>
          <para>A feature of ArgoUML allowing the user to record 
          activities that are yet to be completed.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.transition">

        <glossterm>Transition</glossterm>

        <glossdef>

          <indexterm><primary>Transition</primary></indexterm>
          <para>The change between <emphasis>States</emphasis> in a 
          <emphasis>Statechart Diagram</emphasis>..</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>U</title>

      <glossentry id="gl.uml">

        <glossterm>UML</glossterm>

        <glossdef>

          <indexterm><primary>UML</primary></indexterm>
          <para>Universal Modeling Language. A graphical notation for 
          OOA&amp;D processes, standardized by the OMG. ArgoUML supports 
          UML 1.4. UML 2.0 is in the final stages of standardization
          and should be complete during 2006.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.usecase">

        <glossterm>Use Case</glossterm>

        <glossdef>

          <indexterm><primary>Use Case</primary></indexterm>
          <para>A UML notation for capturing requirements of a system 
          or sub-system. See <xref linkend="s1.tut.req_process_output"/>
           for more information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.usecasediag">

        <glossterm>Use Case Diagram</glossterm>

        <glossdef>

          <indexterm><primary>Use Case Diagram</primary></indexterm>
          <indexterm><primary>Diagram</primary><secondary>Use 
          Case</secondary></indexterm>
          <para>A UML diagram showing the relationships between Actors 
          and Use Cases. See <xref linkend="s1.tut.req_process_output"/>
           for more information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.ucspec">

        <glossterm>Use Case Specification</glossterm>

        <glossdef>

          <indexterm><primary>Use Case 
          Specification</primary></indexterm>
          <para>The document capturing the detailed requirements behind 
          a Use Case.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>V</title>

      <glossentry id="gl.vision">

        <glossterm>Vision Document</glossterm>

        <glossdef>

          <indexterm><primary>Vision Document</primary></indexterm>
          <para>The top level document describing what the system being 
          developed is to achieve.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>W</title>

      <glossentry id="gl.w3c">

        <glossterm>W3C</glossterm>

        <glossdef>

          <indexterm><primary>W3C</primary></indexterm>
          <para>The World Wide Web Consortium, 
          <ulink url="http://www.w3c.org">www.w3c.org</ulink>. An 
          international standardization body for all things to do with 
          the World Wide Web.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.waterfall">

        <glossterm>Waterfall Design Process</glossterm>

        <glossdef>

          <indexterm><primary>Waterfall Design 
          Process</primary></indexterm>
          <indexterm><primary>Design 
          Process</primary><secondary>Waterfall</secondary></indexterm>
          <para>A design process where each phase (requirements, 
          analysis, design, build, test) is completed before the next 
          starts. See <xref linkend="s2.proctypes"/> for more 
          information.</para>

        </glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>X</title>

      <glossentry id="gl.xmi">

        <glossterm>XMI</glossterm>

        <glossdef>

          <indexterm><primary>XMI</primary></indexterm>
          <para>XML Model Interchange format. A format for file storage 
          of UML models. Currently incomplete, since it does not carry 
          all graphical layout information, so must be supplemented by 
          files carrying that information.</para>

        </glossdef>

      </glossentry>

      <glossentry id="gl.xml">

        <glossterm>XML</glossterm>

        <glossdef>

          <indexterm><primary>XML</primary></indexterm>
          <para>eXtensible Markup Language. A simplified derivative of 
          SGML defined by W3C</para>

        </glossdef>

      </glossentry>

    </glossdiv>

  </glossary>

  <appendix id="app.casestudy">

    <title>Supplementary Material for the Case Study</title>

    <sect1>

      <title>Introduction</title>

      <para>The case study requires various material (mostly documents) 
      that live alongside the design diagram</para>

    </sect1>

    <sect1>

      <title>Requirements Documents (To be written)</title>

      <remark>To be written...</remark>
      <sect2>

        <title>Vision Document (To be written)</title>

        <remark>To be written...</remark>
      </sect2>

      <sect2>

        <title>Use Case Specifications (To be written)</title>

        <remark>To be written...</remark>
        <sect3>

          <title>UC Specification 1 (To be written)</title>

          <remark>To be written...</remark>
        </sect3>

      </sect2>

      <sect2>

        <title>Supplementary Requirements Specification (To be 
        written)</title>

        <remark>To be written...</remark>
      </sect2>

    </sect1>

  </appendix>

  <appendix id="app.umlres">

    <title>UML resources</title>

    <sect1>

      <title>The UML specs (To be written)</title>

      <para>To be written...</para>

    </sect1>

    <sect1>

      <title>UML related papers (To be written)</title>

      <para>To be written...</para>

      <sect2>

        <title>UML action specifications (To be written)</title>

        <para>To be written...</para>

      </sect2>

    </sect1>

    <sect1>

      <title>UML related websites (To be written)</title>

      <para>To be written...</para>

    </sect1>

  </appendix>

  <appendix id="app.umlcase">

    <title>UML Conforming CASE Tools</title>

    <sect1>

      <title>Other Open Source Projects (To be written)</title>

      <para>To be written...</para>

    </sect1>

    <sect1>

      <title>Commercial Tools (To be written)</title>

      <para>To be written...</para>

    </sect1>

  </appendix>

  <appendix id="app.cppmod">

    <title>The C++ Module</title>

    <para>The ArgoUML C++ Module (C++ module) provides C++ code 
    generation functionalities and C++ notation within ArgoUML. It 
    works the same way as the other languages&apos; modules.</para>

    <sect1>

      <title>Modeling for C++</title>

      <para>The C++ programming language has constructs that 
      aren&apos;t contained by default in UML. Examples are pointers, 
      global functions and variables, references and operator 
      overloading. To enable us to apply these constructs in our models 
      and be capable of taking advantage of it for code generation and 
      C++ notation in UML diagrams, the C++ module uses conventions in 
      the use of the extension features of UML, such as tagged values, 
      stereotypes and data types.</para>

      <para>Since UML and C++ are object oriented, there is an obvious 
      correspondence between the UML model elements and C++ structural 
      constructs, e.g, the UML <literal>Class</literal> is related to 
      the C++ <literal>class</literal>. These obvious relations will 
      not be described here, since it is assumed that an ArgoUML user 
      that wants to model for C++ has basic knowledge of both C++ and 
      UML.</para>
      
      <para>The C++ module comes with a UML profile for C++, which defines 
      <link linkend="s1.ref.stereotype"><literal>Stereotypes</literal></link> 
      and <link linkend="s1.ref.tagdefinition"><literal>Tagged 
      Definitions</literal></link> 
      which enable the modeling of C++ specific constructs, such as pointers 
      and references.
      It also includes 
      <link linkend="s1.ref.datatype"><literal>Data Types</literal></link> 
      that model the C++ built-in types, such as 
      <literal>unsigned long int</literal>.
      </para>
      
      <para>To have these constructs available in our model, we need to 
      configure the UML profile for C++ in the model explicitly via the Project
      Properties dialog, in the Profiles tab
      (see <xref linkend="s2.ref.menu_properties"/>).
      </para>

      <para>Tagged values are one of the main means by which we can 
      define code generation behavior. 
      They have a name - the tag - and 
      a value, and are applied to model elements.
      For each of the possible Tagged values, the C++ profile contains a 
      tag definition, which is contained in a stereotype, applicable to the 
      models elements to which we can define a tagged value's value to specify 
      specific behaviour.
      So, for instance, to define that the parameter <literal>x</literal> is a 
      reference, you apply the stereotype <literal>cppParameter</literal> to 
      it, them you add the tagged value <literal>reference</literal> with the 
      value <literal>true</literal>.
      </para>

      <para>The tagged values in use for the C++ module have two 
      categories:</para>

      <itemizedlist>

        <listitem>

          <para>free format values - any <literal>String</literal> is 
          valid, except the empty <literal>String</literal></para>

        </listitem>

        <listitem>

          <para>formated values - the value must obey some 
          restrictions, e.g., be one of <literal>true</literal> or 
          <literal>false</literal> (abbreviated to <literal>true || 
          false</literal>)</para>

        </listitem>

      </itemizedlist>

      <para>For <literal>Boolean</literal> tagged values, only the 
      values &quot;<literal>true</literal>&quot; or &quot;
      <literal>false</literal>&quot; are applicable. If a <literal>
      Boolean</literal> tagged value does not exist or is invalid for 
      one model element, a default value is assumed by the code 
      generator. In the bellow documentation the default value is 
      marked.</para>

      <para>Free format tagged values are only significant if present 
      and if the value isn&apos;t an empty <literal>String</literal>. 
      When the value must follow some sort of format, that is 
      explicitly stated. In this case, there is the chance that the 
      value is invalid. If the value is invalid, no assumptions are 
      made; the generator will trace the problem and ignore the tagged 
      value.</para>

      <sect2>

        <title><literal>Class</literal> tagged values</title>
        
        <para>To make the tag definitions applicable to a C++ class available 
        we apply the <literal>cppClass</literal> stereotype to it.
        </para>

        <variablelist>

          <varlistentry>

            <term><literal>constructor</literal></term>

            <listitem>

              <para><literal>true</literal> - generates a default 
              constructor for the <literal>class</literal>.</para>

              <para><literal>false</literal> (default) - no default 
              constructor is generated, unless it is explicitly modeled 
              with the <literal>&laquo;create&raquo;</literal> stereotype.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>header_incl</literal></term>

            <listitem>

              <para>Name of the file to include in the header.</para>

              <note>

                <para>If we desire to have multiple headers included 
                this way, just use multiple tagged values with <literal>
                header_incl</literal> as the tag.</para>

                <para>Other tagged values used for C++ modeling may 
                also be used this way. This note won&apos;t be repeated 
                in those cases.</para>

              </note>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>source_incl</literal></term>

            <listitem>

              <para>Name of the file to include in the source (
              <literal>.cpp</literal> file).</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>typedef_public</literal></term>

            <listitem>

              <para><literal>&lt;source type&gt; 
              &lt;type_name&gt;</literal> - creates <literal>
              typedef</literal> line in the public area of the <literal>
              class</literal> with <literal>typedef &lt;source type&gt; 
              &lt;type name&gt;</literal>.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>typedef_protected</literal></term>

            <listitem>

              <para>Same as <literal>typedef_public</literal>, but, in 
              <literal>protected</literal> area.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>typedef_private</literal></term>

            <listitem>

              <para>Same as <literal>typedef_public</literal>, but, in 
              the <literal>private</literal> area.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>typedef_global_header</literal></term>

            <listitem>

              <para>Same as <literal>typedef_public</literal>, but, in 
              the global area of the header.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>typedef_global_source</literal></term>

            <listitem>

              <para>Same as <literal>typedef_global_source</literal>, 
              but, in the source file.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>TemplatePath</literal></term>

            <listitem>

              <para><literal>Directory</literal> - will search in the 
              specified directory for the template files 
              &quot;header_template&quot; and &quot;cpp_template&quot; 
              which are placed in top of the corresponding file. The 
              following tags in the template file are replaced by model 
              values: |FILENAME|, |DATE|, |YEAR|, |AUTHOR|, |EMAIL|. If 
              no such tag is specified, the templates are searched in 
              the subdirectory of the root directory for the code 
              generation.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>email</literal></term>

            <listitem>

              <para><literal>name@domain.country</literal> - replaces 
              the tag |EMAIL| of the template file.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>author</literal></term>

            <listitem>

              <para><literal>name</literal> - replaces the tag |AUTHOR| 
              of the template file.</para>

              <note>

                <para>You may simply use the Author property in the 
                documentation property panel.</para>

              </note>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect2>

      <sect2>

        <title><literal>Attribute</literal> tagged values</title>

        <para>UML <literal>Attributes</literal> are mapped to <literal>
        class member variables</literal>.
        To make the tag definitions applicable to a C++ member variable 
        available we apply the <literal>cppAttribute</literal> stereotype to 
        it.</para>

        <variablelist>

          <varlistentry>

            <term><literal>pointer</literal></term>

            <listitem>

              <para><literal>true</literal> - the type of the member 
              variable will be a pointer to the attribute type.</para>

              <para>For example, if you have the UML <literal>
              Attribute</literal>: <literal>name: 
              std::string</literal>, with the <literal>
              pointer</literal> tagged value set to true, the generated 
              member variable would be: <literal>std::string* 
              name;</literal></para>

              <para><literal>false</literal> (default) - no pointer 
              modifier is applied.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>reference</literal></term>

            <listitem>

              <para><literal>true</literal> - the type of the member 
              variable will be a reference to the attribute type.</para>

              <para><literal>false</literal> (default) - no reference 
              modifier is applied.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>usage</literal></term>

            <listitem>

              <para><literal>header</literal> - will lead for class 
              types to a pre-declaration in the header, and the include 
              of the remote class header in the header of the generated 
              class.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>MultiplicityType</literal></term>

            <listitem>

              <para><literal>list || slist || vector || map || stack || 
              stringmap</literal> - will define a multiplicity as the 
              corresponding STL container, if the <literal>
              Multiplicity</literal> range of the attribute is variable 
              (for fixed size ranges this setting is ignored).</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>set</literal></term>

            <listitem>

              <para><literal>private || protected || public</literal> - 
              creates a simple function to set the attribute by a 
              function (call by reference is used for class-types, else 
              call by value); place the function in the given 
              visibility area.</para>

            </listitem>

          </varlistentry>

          <varlistentry>

            <term><literal>get</literal></term>

            <listitem>

              <para><literal>private || protected || public</literal> - 
              as for <literal>set</literal>.</para>

            </listitem>

          </varlistentry>

        </variablelist>

      </sect2>

      <sect2>

        <title><literal>Parameters</literal></title>
        
        <para>To make the tag definitions applicable to a C++ argument 
        available we apply the <literal>cppParameter</literal> stereotype to 
        it.
        </para>

        <sect3>

          <title>Variable passing semantics</title>

          <para>If a <literal>Parameter</literal> for an <literal>
          Operation</literal> is marked as <literal>out</literal> or 
          <literal>inout</literal> the variable will be passed by 
          reference (default) or pointer (needs tagged value <literal>
          pointer</literal> - see above), otherwise by value.</para>

          <para>Return values in UML are simply <literal>
          Parameters</literal> marked as <literal>return</literal>, 
          therefore everything here applies to them, except where 
          explicitly noted.</para>

          <warning>

            <para>Note that UML allows multiple return values. This is 
            possible to support in C++ as out parameters, but, 
            currently the generator doesn&apos;t supports it.</para>

            <para>This problem is being handled in 
            <ulink url="http://argouml.tigris.org/issues/show_bug.cgi?id=3553">
            issue #3553 - handle multiple return 
            parameters</ulink>.</para>

          </warning>

        </sect3>

        <sect3>

          <title><literal>Parameter</literal> tagged values</title>

          <variablelist>

            <varlistentry>

              <term><literal>pointer</literal></term>

              <listitem>

                <para><literal>true || false</literal> (default) - same 
                as for <literal>Attributes</literal>.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>reference</literal></term>

              <listitem>

                <para>ditto</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect3>

      </sect2>

      <sect2>

        <title><literal>Generalization</literal></title>
        
        <para>To make the tag definitions applicable to a C++ generalization 
        available we apply the <literal>cppGeneralization</literal> 
        stereotype to it.
        </para>

        <sect3>

          <title><literal>Generalization</literal> tagged values</title>

          <variablelist>

            <varlistentry>

              <term><literal>cpp_virtual_inheritance</literal></term>

              <listitem>

                <para><literal>true || false</literal> (default) - used to 
                specify virtual inheritance.</para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><literal>cpp_inheritance_visibility</literal></term>

              <listitem>

                <para><literal>public</literal> (default)<literal> || private 
                || protected</literal> &ndash; use this to specify the 
                inheritance visibility of the generalization.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect3>

      </sect2>

      <sect2>

        <title><literal>Realization</literal></title>
        
        <para>To make the tag definitions applicable to a C++ realization 
        available we apply the <literal>cppRealization</literal> 
        stereotype to it.
        </para>

        <sect3>

          <title><literal>Realization</literal> tagged values</title>

          <variablelist>

            <varlistentry>

              <term><literal>cpp_inheritance_visibility</literal></term>

              <listitem>

                <para><literal>public</literal> (default)<literal> || private 
                || protected</literal> &ndash; use this to specify the 
                inheritance visibility of the generalization.</para>

              </listitem>

            </varlistentry>

          </variablelist>

        </sect3>

      </sect2>

      <sect2>

        <title>Preserved sections</title>

        <para>With each code generation, special comments around the 
        member function definitions will be generated like this:</para>

        <programlisting>
  function Testclass::Testclass()
  // section -64--88-0-40-76f2e8:ec37965ae0:-7fff begin
 {
 }
  // section -64--88-0-40-76f2e8:ec37965ae0:-7fff end
      </programlisting>
        <para>All code you put within the &quot;begin&quot; and 
        &quot;end&quot; lines will be preserved when you generate the 
        code again. Please do not change anything within these lines 
        because the sections are recognized by this comment syntax. As 
        the curly braces are placed within the preserved area, 
        attribute initializers are preserved on constructors.</para>

        <para>This also works if you change Method Names after the 
        generation.</para>

        <programlisting>
  void newOperation(std::string test = &quot;fddsaffa&quot;)
  // section 603522:ec4c7ff768:-7ffc begin
 {
 }
  // section 603522:ec4c7ff768:-7ffc end
      </programlisting>
        <para>If you delete an Operation in the model. The next time 
        the class is generated, the lost code - i.e., the whole member 
        function definition - will be added as comment to the end of 
        the file.</para>

      </sect2>

    </sect1>

  </appendix>

  <appendix id="app.hardlimits">

    <title>Limits and Shortcomings</title>

    <para>As all products, ArgoUML has some limits. Those important to 
    the user are listed in this section.</para>

    <sect1>

      <title>Diagram Canvas Size</title>

      <para>Due to the underlying diagram editing software, the canvas 
      size for diagrams is limited to 6000 units in height and 
      width.</para>

    </sect1>

    <sect1>

      <title>Missing functions</title>
      <para></para>


    </sect1>

  </appendix>

  <appendix id="app.legal">

    <title>Open Publication License</title>

    <sect1>

      <title>Requirements On Both Unmodified And Modified 
      Versions</title>

      <para>The Open Publication works may be reproduced and 
      distributed in whole or in part, in any medium physical or 
      electronic, provided that the terms of this license are adhered 
      to, and that this license or an incorporation of it by reference 
      (with any options elected by the author(s) and/or publisher) is 
      displayed in the reproduction.</para>

      <para>Proper form for an incorporation by reference is as 
      follows:</para>

      <blockquote>

        <para>Copyright (c) &lt;year&gt; by &lt;author&apos;s name or 
        designee&gt;. This material may be distributed only subject to 
        the terms and conditions set forth in the Open Publication 
        License, vX.Y or later (the latest version is presently 
        available at <ulink url="http://www.opencontent.org/openpub/">
        http://www.opencontent.org/openpub/</ulink>).</para>

      </blockquote>

      <para>The reference must be immediately followed with any options 
      elected by the author(s) and/or publisher of the document (see 
      section VI).</para>

      <para>Commercial redistribution of Open Publication-licensed 
      material is permitted.</para>

      <para>Any publication in standard (paper) book form shall require 
      the citation of the original publisher and author. The publisher 
      and author&apos;s names shall appear on all outer surfaces of the 
      book. On all outer surfaces of the book the original 
      publisher&apos;s name shall be as large as the title of the work 
      and cited as possessive with respect to the title.</para>

    </sect1>

    <sect1>

      <title>Copyright</title>

      <para>The copyright to each Open Publication is owned by its 
      author(s) or designee.</para>

    </sect1>

    <sect1>

      <title>Scope Of License</title>

      <para>The following license terms apply to all Open Publication 
      works, unless otherwise explicitly stated in the document.</para>

      <para>Mere aggregation of Open Publication works or a portion of 
      an Open Publication work with other works or programs on the same 
      media shall not cause this license to apply to those other works. 
      The aggregate work shall contain a notice specifying the 
      inclusion of the Open Publication material and appropriate 
      copyright notice.</para>

      <para>SEVERABILITY. If any part of this license is found to be 
      unenforceable in any jurisdiction, the remaining portions of the 
      license remain in force.</para>

      <para>NO WARRANTY. Open Publication works are licensed and 
      provided <quote>as is</quote> without warranty of any kind, 
      express or implied, including, but not limited to, the implied 
      warranties of merchantability and fitness for a particular 
      purpose or a warranty of non-infringement.</para>

    </sect1>

    <sect1>

      <title>Requirements On Modified Works</title>

      <para>All modified versions of documents covered by this license, 
      including translations, anthologies, compilations and partial 
      documents, must meet the following requirements:</para>

      <orderedlist>

        <listitem>

          <para>The modified version must be labeled as such.</para>

        </listitem>

        <listitem>

          <para>The person making the modifications must be identified 
          and the modifications dated.</para>

        </listitem>

        <listitem>

          <para>Acknowledgement of the original author and publisher if 
          applicable must be retained according to normal academic 
          citation practices.</para>

        </listitem>

        <listitem>

          <para>The location of the original unmodified document must 
          be identified.</para>

        </listitem>

        <listitem>

          <para>The original author&apos;s (or authors&apos;) name(s) 
          may not be used to assert or imply endorsement of the 
          resulting document without the original author&apos;s (or 
          authors&apos;) permission.</para>

        </listitem>

      </orderedlist>

    </sect1>

    <sect1>

      <title>Good-Practice Recommendations</title>

      <para>In addition to the requirements of this license, it is 
      requested from and strongly recommended of redistributors 
      that:</para>

      <orderedlist>

        <listitem>

          <para>If you are distributing Open Publication works on 
          hardcopy or CD-ROM, you provide email notification to the 
          authors of your intent to redistribute at least thirty days 
          before your manuscript or media freeze, to give the authors 
          time to provide updated documents. This notification should 
          describe modifications, if any, made to the document.</para>

        </listitem>

        <listitem>

          <para>All substantive modifications (including deletions) be 
          either clearly marked up in the document or else described in 
          an attachment to the document.</para>

        </listitem>

        <listitem>

          <para>Finally, while it is not mandatory under this license, 
          it is considered good form to offer a free copy of any 
          hardcopy and CD-ROM expression of an Open 
          Publication-licensed work to its author(s).</para>

        </listitem>

      </orderedlist>

    </sect1>

    <sect1>

      <title>License Options</title>

      <para>The author(s) and/or publisher of an Open 
      Publication-licensed document may elect certain options by 
      appending language to the reference to or copy of the license. 
      These options are considered part of the license instance and 
      must be included with the license (or its incorporation by 
      reference) in derived works.</para>

      <para>A. To prohibit distribution of substantively modified 
      versions without the explicit permission of the author(s). 
      <quote>Substantive modification</quote> is defined as a change to 
      the semantic content of the document, and excludes mere changes 
      in format or typographical corrections.</para>

      <para>To accomplish this, add the phrase <quote>Distribution of 
      substantively modified versions of this document is prohibited 
      without the explicit permission of the copyright holder.</quote> 
      to the license reference or copy.</para>

      <para>B. To prohibit any publication of this work or derivative 
      works in whole or in part in standard (paper) book form for 
      commercial purposes is prohibited unless prior permission is 
      obtained from the copyright holder.</para>

      <para>To accomplish this, add the phrase <quote>Distribution of 
      the work or derivative of the work in any standard (paper) book 
      form is prohibited unless prior permission is obtained from the 
      copyright holder.</quote> to the license reference or copy.</para>

    </sect1>

    <sect1>

      <title>Open Publication Policy Appendix:</title>

      <para>(This is not considered part of the license.)</para>

      <para>Open Publication works are available in source format via 
      the Open Publication home page at 
      <ulink url="http://works.opencontent.org/">
      http://works.opencontent.org/</ulink>.</para>

      <para>Open Publication authors who want to include their own 
      license on Open Publication works may do so, as long as their 
      terms are not more restrictive than the Open Publication 
      license.</para>

      <para>If you have questions about the Open Publication License, 
      please contact <ulink url="mailto:dw2@opencontent.org">David 
      Wiley</ulink>, and/or the Open Publication Authors&apos; List at 
      <ulink url="mailto:opal@opencontent.org">
      opal@opencontent.org</ulink>, via email.</para>

      <para>To <emphasis>subscribe</emphasis> to the Open Publication 
      Authors&apos; List: Send E-mail to opal-request@opencontent.org 
      with the word <quote>subscribe</quote> in the body.</para>

      <para>To <emphasis>post</emphasis> to the Open Publication 
      Authors&apos; List: Send E-mail to opal@opencontent.org or simply 
      reply to a previous post.</para>

      <para>To <emphasis>unsubscribe</emphasis> from the Open 
      Publication Authors&apos; List: Send E-mail to 
      opal-request@opencontent.org with the word 
      <quote>unsubscribe</quote> in the body.</para>

    </sect1>

  </appendix>

  <appendix id="app.crc">

    <title>The CRC Card Methodology</title>

    <para>
      A CRC card is ostensibly an index card that is used to represent
      classes, their responsibilities, and the interactions between them.
      The term CRC card is also used to refer to a methodology for object
      oriented modeling based on their use.
    </para>

    <para>
      Kent Beck and Ward Cunningham introduced CRC cards in a paper
      "A Laboratory for Teaching Object-Oriented Thinking" that was presented at
      the OOPSLA (Object-Oriented Programming, Systems, Languages &amp; Applications)
      conference in 1989.
      A tutorial on the subject can be found at
      <ulink url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/crc_b/"/>.
      The CRC card methodology was originally designed as a teaching tool but
      has proved useful as a modeling tool as well.
    </para>

    <para>
      The three parts of the CRC acronym were felt by the authors of the
      paper to represent the essential dimensions of object oriented modeling.
      The term Responsibilities refers to the contract that the class
      under discussion offers to the rest of the world (Interface and
      Contract are similar concepts).
      Responsibilities model the things that a class can do.
      Services, Methods, or Operations will result from these.
      The term Collaborators refers to the classes whose services
      the class under discussion will use.
      Kent Beck tried unsuccessfully to use ther term Helpers instead of
      Collaborators to indicate classes that were supporting the class under
      discussion.
      It is widely believed that the terminology was chosen because CRC are
      the initials of Ward Cunningham's son.
    </para>

    <para>
      Why use CRC cards?
      <itemizedlist>
        <listitem><para>
          They are portable.
          No computers are required so they can be used anywhere.
          Even away from the office.</para>
        </listitem>
        <listitem><para>
          They allow the participants to experience first hand
          how the system will work.
          No computer tool can replace the interaction that happens by
          physically picking up the cards and playing the role of that object.</para>
        </listitem>
        <listitem><para>
          They are a useful tool for teaching people the object-oriented
          paradigm.</para>
        </listitem>
        <listitem><para>
          They can be used as a methodology themselves or as a front end to a
          more formal methodology such as Booch, Wirfs-Brock, Jacobson, etc.
          Although CRC cards were created for teaching, they have proven
          useful for much more.</para>
        </listitem>
        <listitem><para>
          They have become an accepted method for analysis and design.
          The biggest contributing factor to their success is the fact that they
          provide an informal and non threatening environment that is
          productive to working and learning.</para>
        </listitem>
      </itemizedlist>
    </para>

    <sect1>

      <title>The Card</title>

      <para>
        The exact format of the card can be customized to the preferences of
        the group, but the minimal required information is the name of the
        class, it's subclasses and superclasses, it's responsibilities
        and the collaborators for each of those responsibilities.
        The back of the card can be used for a description of the class.
        During the design phase attributes of the class can be recorded on
        the back as well.
        One way to think of the card is that the front contains
        the public information, and the back contains the encapsulated,
        implementation details.
        As a class is defined a card is made for that class with
        its name entered.
        When a class is assigned to an individual that has only a class name
        on it, the individual (or the group) selects an initial set of
        responsibilities for the class.
        This initial set should be whatever (if anything) is
        immediately obvious.
      </para>

    </sect1>

    <sect1>

      <title>The Group</title>

      <para>
        Whether they are implicitly or explicitly defined the requirements
        for the system need to be familiar to the people participating
        in the group.
      </para>

      <para>
        The ideal group size for a CRC card session is five or six people.
        This size generally allows everyone to productively participate.
        In groups of larger size productivity is cut by more disagreements and
        the amount of participation by each is lower.
        If there are more than six people, one solution is to have the extra
        people be present strictly as observers.
      </para>

      <para>
        The group five or six people in the core group should be composed of
        developers, domain experts, and an object-oriented
        technology facilitator.
      </para>

    </sect1>

    <sect1>

      <title>The Session</title>

      <para>
        Before starting a session a part of the problem needs to be selected
        for the session to focus on.
        Essentially, this means picking the set of classes that are
        to be used.
      </para>

      <para>
        Pick the scenarios that are to be walked through that use the classes
        picked above.
        Start with scenarios that are part of the systems normal operation
        first, and then exceptional scenarios, like error recover, later.
      </para>

      <para>
        Assign each class to a member of the group.
        Each person should be responsible for at least one class.
        They are the owner of that class for the session.
        Each person records the name of their class on a card.
        One class per card.
      </para>

      <para>
        Walk-throughs are the heart of the CRC card session.
        To walk through a scenario address each action in it one at a time.
        First decide which class is responsible for this function.
        The owner of the class then picks up his card and
        holds it up in the air.
        When a card is up in the air it is an object and can do things.
        The owner announces that he needs to fulfill his responsibility.
        The responsibility is refined into smaller tasks if possible.
        These smaller tasks can be fulfilled by the object is appropriate or
        they can be fulfilled by interacting with other objects
        (collaborators).
        If no other appropriate class exists, you may need to make one
        and assign it to someone.
        This is the fundamental procedure of the scenario execution.
      </para>

    </sect1>

    <sect1>

      <title>The Process</title>


      <para>
        CRC Cards are used in the Analysis and Design phases.
        The process for these phases differ primarily in how the classes
        and scenarios are chosen.
      </para>

      <para>
        In the Analysis phase the classes and scenarios are in the problem
        space and generally derive from the requirements.
        In the Design phase solution space classes and scenarios are added.
        Additionally in the Analysis phase the very first session starts with
        no classes or scenarios to select from so a special session creates
        them.
      </para>

    </sect1>

  </appendix>

  <index>

    <para>The use of the index in the document is done a little at 
    random and cannot be trusted. Please help in suggesting new index 
    entries!</para>

  </index>

</book>

