KDevelop4/Manual/Plugins: Code Generation: Difference between revisions

From KDE Wiki Sandbox
(Import from old KDevelop wiki)
 
(Moved title to start of page)
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''DRAFT - Work in progress'''
== How To ==
 
{{Construction}}
 
=== Files organization ===


KDevelop Code Generation plugin uses [http://grantlee.org Grantlee template engine] to generate code (like classes, functions, code documentation etc.).
The Code Generation plugin files are located into the [http://techbase.kde.org/KDE_System_Administration/KDE_Filesystem_Hierarchy#Directory_Tree KDE user data directory] of KDevelop.


The goal of KDevelop's Grantlee implementation is to provide a '''very flexible template system'''. The architecture is based on 3 main concepts which results as resources for the plugin:
Each resource has its own folder :
* Template
* Context
* Generator


== Resources ==
* codegeneration/
=== Template ===
** templates/
The template define the body of the generated code.
** contexts/
** generators /
 
=== Flexibility ===
 
As Code Generation plugin is very flexible, you do not need to create templates, contexts and generators for simple tasks.
 
You can edit a template to modify generated source code using the same contexts. If provided data are not enough, modify the context and use your new variables in your template or simply add existing contexts.


Templates syntax is the same as the [http://www.grantlee.org/apidox/for_themers.html Grantlee templates syntax]. All features provided by its engine are available.
=== Creating your context ===
The first step is to create a new widget with Qt Designer.


=== Context ===
{{ Info | Do not add usual dialog buttons ("Finish", "Cancel", etc.). Your widget will be inserted into a standard wizard. }}
The context handles both the '''user interface''' and the '''data available to the template'''.


The user interface is what the end-user uses to configure the template. You should use Qt UIs files created with [http://doc.qt.nokia.com/4.7-snapshot/designer-manual.html Qt Designer] to define your own context.
[[Image:CreateForm.png|frame|center|Creating your context as a simple Widget]]


Code Generation plugin uses form fields to generate data. Typically, binary valued fields (checkboxs) will result as booleans, single valued fields (text fields, text areas, single selection lists, radio buttons) as strings and multi valued fields (multiple selection lists) as lists of strings.
Then add a new dynamic property called '''contextName'''. Set up the value with the name of your context.


For convenience, all variables defined in a context are included in a namespace. It enables the use of '''several contexts into a single template''' without variables names conflict.
{{Tip|Try to find an unique context name to avoid conflicts.}}


==== Global contexts ====
[[Image:ContextName.png|frame|center|Seting up the name of your context]]
Many global contexts are always available in any template. They give data which does not need to be configurable by the end-user.


Currently available global contexts are :
It's time to define your data. Add many fields into your form. Use layouts, labels and others setup tools to make your own dialog. They will do not produce any data.
* [[KDevelop_4/Code_Generation/Global_Contexts/Environment | environment]]
* [[KDevelop_4/Code_Generation/Global_Contexts/File | file]]
* [[KDevelop_4/Code_Generation/Global_Contexts/Class | class]]
* [[KDevelop_4/Code_Generation/Global_Contexts/Function | function]]


=== Generator ===
[[Image:ContextExample.png|frame|center|Making your own context]]
The generator contains the templates and contexts used to generate a coherent object (a class, a function, the documentation for an item in the code etc.).


The generator also define outputs. Each template is associated to one output where generated code will be put.
Take care of the fields names. They will be used to generate variables in the template.


'''A generator will result as a new entry''' in the Code Generation menu.
[[Image:ContextVariablesNames.png|frame|center|Defining variables names]]


== How To ==
Like previously mentionned, each kind of form field will produce a different data type:
=== Files organization ===
* '''name''' will be a string containing the name of the class
* '''baseClasses''' will be a list of string containing the names of base classes
* all '''implements*''' fields will be boolean


The Code Generation plugin files are located into the [http://techbase.kde.org/KDE_System_Administration/KDE_Filesystem_Hierarchy#Directory_Tree KDE user data directory] of KDevelop (default ''~/.kde4/share/apps/kdevelop/codegeneration/'').
All variables names wil be prefixed by the context name : '''MyCppClassContext.name''', '''MyCppClassContext.baseClasses''', etc.


Each resource has its own folder :


Now, you can save your context in an UI file named '''<contextName>.ui''':
* codegeneration/
* codegeneration/
** templates/
** templates/
** contexts/
** contexts/
** generators /
*** MyCppClassContext.ui
** generators/
 
=== Using data in your template ===


=== Flexibility ===
Create a simple text file '''<templateName>.tpl''':


As Code Generation plugin is very flexible, you do not need to create templates, contexts and generators for simple tasks.
* codegeneration/
** templates/
*** MyCppClassTemplate.tpl
** contexts/
*** MyCppClassContext.ui
** generators/


You can edit a template to modify generated source code using the same contexts. If provided data are not enough, modify the context and use your new variables in your template or simply add existing contexts.
Use data you have defined into your context :


=== Creating your context ===
{{Input|<syntaxhighlight lang="cpp" line>
The first step is to create a new ''widget'' with Qt Designer.
#ifndef {{ MyCppClassContext.name }}
#define {{ MyCppClassContext.name }}


[[Image:CreateForm.png|frame|center|Creating your context as a simple Widget]]
class {{ MyCppClassContext.name }} : {% for %}{% endfor %}
{
}


Then add a new dynamic property called ''contextName''. Set up the value with the name of your context. Try to find an unique name to avoid conflicts.
#endif // {{ MyCppClassContext.name }}
</syntaxhighlight>}}


[[Image:ContextName.png|frame|center|Setting up the name of your context]]
== See also ==
{{TechbaseLink|KDevelop4/Plugins:_Code_Generation}}


[[User:Damien.flament|Damien.flament]]
[[Category:Development]]

Latest revision as of 19:11, 17 August 2012

How To

Under Construction
This is a new page, currently under construction!


Files organization

The Code Generation plugin files are located into the KDE user data directory of KDevelop.

Each resource has its own folder :

  • codegeneration/
    • templates/
    • contexts/
    • generators /

Flexibility

As Code Generation plugin is very flexible, you do not need to create templates, contexts and generators for simple tasks.

You can edit a template to modify generated source code using the same contexts. If provided data are not enough, modify the context and use your new variables in your template or simply add existing contexts.

Creating your context

The first step is to create a new widget with Qt Designer.

Information
Do not add usual dialog buttons ("Finish", "Cancel", etc.). Your widget will be inserted into a standard wizard.


Creating your context as a simple Widget

Then add a new dynamic property called contextName. Set up the value with the name of your context.

Tip
Try to find an unique context name to avoid conflicts.


Seting up the name of your context

It's time to define your data. Add many fields into your form. Use layouts, labels and others setup tools to make your own dialog. They will do not produce any data.

Making your own context

Take care of the fields names. They will be used to generate variables in the template.

Defining variables names

Like previously mentionned, each kind of form field will produce a different data type:

  • name will be a string containing the name of the class
  • baseClasses will be a list of string containing the names of base classes
  • all implements* fields will be boolean

All variables names wil be prefixed by the context name : MyCppClassContext.name, MyCppClassContext.baseClasses, etc.


Now, you can save your context in an UI file named <contextName>.ui:

  • codegeneration/
    • templates/
    • contexts/
      • MyCppClassContext.ui
    • generators/

Using data in your template

Create a simple text file <templateName>.tpl:

  • codegeneration/
    • templates/
      • MyCppClassTemplate.tpl
    • contexts/
      • MyCppClassContext.ui
    • generators/

Use data you have defined into your context : 

#ifndef {{ MyCppClassContext.name }}
#define {{ MyCppClassContext.name }}

class {{ MyCppClassContext.name }} : {% for %}{% endfor %}
{
}

#endif // {{ MyCppClassContext.name }}

See also

The KDevelop4/Plugins:_Code_Generation page on Techbase.

Retrieved from "https://wikisandbox.kde.org/index.php?title=KDevelop4/Manual/Plugins:_Code_Generation&oldid=261774"