tdesdk/doc/umbrello/code_import_and_generation.docbook

<chapter id="code-import-generation">
<title>Code Import and Code Generation</title>
<para>
&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the 
<emphasis>analysis and design</emphasis> of your systems. However, to make the transition
between your design and your <emphasis>implementation</emphasis>, &umbrello; allows you to
generate source code in different programming languages to get you started. Also, if you 
want to start using &UML; in an already started C++ project, &umbrello; can help you create a model
of your system from the source code by analysing your source code and importing the classes
found in it.
</para>
<sect1 id="code-generation">
<title>Code Generation</title>
<para>
&umbrello; can generate source code for various programming languages based on your &UML; Model
to help you get started with the implementation of your project. The code generated consists
of the class declarations, with their methods and attributes so you can <quote>fill in the
blanks</quote> by providing the functionality of your classes' operations.
</para>
<para>
&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, <acronym>PHP</acronym>, Perl, Python, SQL and XMLSchema. 
</para>
<sect2 id="generate-code">
<title>Generating Code</title>
<para>
In order to generate code with &umbrello;, you first need to create or load a Model
containing at least one class. When you are ready to start writing some code, select the
<guimenuitem>Code Generation Wizard</guimenuitem> entry from the <guimenuitem>Code</guimenuitem> menu to 
start a wizard which will guide you trough the code generation process.
</para>
<para>
The first step is to select the classes for which you want to generate source code.
By default all the classes of your model are selected, and you can remove the ones
for which you do not want to generate code by moving them to the left-hand side list.
</para>
<para>
The next step of the wizard allows you to modify the parameters the Code Generator uses
while writing your code. The following options are available:
</para>
<para>
<screenshot>
<screeninfo>Code Generation Options</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="generation-options.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Options for the Code Generation in &umbrello;</phrase>
	  </textobject>
	  <caption>
	    <para>Options for the Code Generation in &umbrello;
	    </para>
	  </caption>
	</mediaobject>
</screenshot>
</para>
<sect3 id="generation-options">
<title>Generation Options</title>
<!-- LW; to rearrange -->

<sect4>
<title>Code Verbosity</title>
<para>
The option <guilabel>Write documentation comments even if empty</guilabel> instructs the
 Code Generator to write comments of the /** blah */ style even if the comment blocks are empty.
If you added documentation to your classes, methods or attributes in your Model, the
Code Generator will write these comments as <application>Doxygen</application> documentation regardless of what you set here, but
if you select this option &umbrello; will write comment blocks for all classes, methods and attributes
even if there is no documentation in the Model, in which case you should document your classes
later directly in the source code.
</para>
<para>
<guilabel>Write comments for sections even if section is empty</guilabel> causes &umbrello; to write comments
in the source code to delimit the different sections of a class. For example <quote>public methods</quote>
 or <quote>Attributes</quote> before the corresponding sections. If you select this option &umbrello; 
 will write comments for all sections of the class even if the section is empty. For example,
 it would write a comment saying <quote>protected methods</quote> even if there are no protected 
 methods in your class.
</para>
</sect4>
<sect4>
<title>Folders</title>
<para>
<guilabel>Write all generated files to folder</guilabel>. Here you should select the folder 
where you want &umbrello; to put the generated sources.
</para>
<para>
The <guilabel>Include heading files from folder</guilabel> option allows you to insert a 
heading at the beginning of each generated file. Heading files can contain copyright or licensing
 information and contain variables that are evaluated at generation time. You can take a look
 at the template heading files shipped with &umbrello; to see how to use this variables for replacing
 your name or the current date at generation time.
</para>
</sect4>
<sect4>
<title>Overwrite Policy</title>
<!-- FIXME update for Umbrello 1.2's new C++ and Java code generators -->
<para>
This option tells &umbrello; what to do if the file it wants to create already exists in
the destination folder. &umbrello; <emphasis>cannot modify existing source files</emphasis>,
so you have to choose between overwriting the existing file, skipping the generation of
that particular file or letting &umbrello; choose a different file name. If you choose the option
to use a different name, &umbrello; will add a suffix to the file name.
</para>
</sect4>
<sect4>
<title>Language</title>
<para>
&umbrello; will by default generate code in the language you have selected as Active Language, but
with the Code Generation Wizard you have the option to change this to another language.
</para>
</sect4>
</sect3><!--generation-options-->
<sect3 id="generation-wizard-generation">
<title>Generation Wizard Generation</title>
<para>
The third and last step of the wizard shows the status of the Code Generation process.
You need only to click on the Generate button to get your classes written for you.
</para>
<para>
Note that the Options you select during the Code Generation Wizard are only valid for the current
generation. The next time you run the wizard you will need to re-select all the options
(your headings folder, overwrite policy, and so on). You can set the defaults used by &umbrello; 
in the <guilabel>Code Generation</guilabel> section of the &umbrello; settings, available
at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &umbrello;...</guimenuitem></menuchoice>
</para>
<para>
If you have set your Code Generation options to the right settings and want to generate
some code right away without going through the wizard, you can select the entire 
<guimenuitem>Generate All Code</guimenuitem> from the Code menu. 
This will generate code for all the classes in your Model using the current settings 
(including Output Folder and Overwrite Policy, so use with care).
</para>
</sect3>
</sect2><!--generate-code-->
</sect1> <!--code-generation-->
<sect1 id="code-import">
<title>Code Import</title>
<para>
&umbrello; can import source code from your existing projects to help you build Model of 
your systems. &umbrello; 1.2 supports only C++ source code, but other languages
should be available in future versions.
</para>
<para>
To import classes into your Model, select the entry <guimenuitem>Import Classes...</guimenuitem> from
the <guimenu>Code</guimenu> menu. In the file dialog select the files containing the C++
class declarations and press OK. The classes will be imported and you will find them as part of
your Model in the Tree View. Note that &umbrello; will not create any kind of Diagram for showing
your classes, they will only be imported into your Model so that you can use them later in any 
diagram you want.
</para>
<para>
<screenshot>
<screeninfo>Code Import</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="code-import.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Menu for importing source code in &umbrello;</phrase>
	  </textobject>
	  <caption>
	    <para>Menu for importing source code in &umbrello;
	    </para>
	  </caption>
	</mediaobject>
</screenshot>
</para>
</sect1>
</chapter> <!--code-import-generation-->