en:dev

C/C++ Code Style for NCL Composer

2017-02-03T16:31:17-03:00

This page is a draft!

C/C++ Code Style for NCL Composer

As any project, keep code standard is important to improve the quality of the software, improve reusability and a software which is easier to maintain.

The NCL Composer Code style is similar to most of the C++ projects. So, you will easily navigate through the source code. Here, we will discuss some issues of our code style.

Class Template

The following code shows a template that should be followed when defining a class:

namespace composer {
namespace core {
namespace model {
/*!
 \brief Description of the class
 */
class MyClass
{
// Class Content
};
 
} } } //end namespace

It is recommended to keep the final comment informing that line is finishing the namespace.

Contributing

2017-02-03T16:31:17-03:00

Contributing

NCL Composer is an open source project, so we are always open to any kind of contribution.

As well pointed by Andy Lester in 14 Ways to Contribute to Open Source without Being a Programming Genius or a Rock Star blog post, you do not need to be a Genius Programmer to contribute to any open source project (including NCL Composer). So, if you want to contribute: Do not hesitate!!!

If you are not a programmer, you can contribute to NCL Composer, through:

Reporting BUGs
Suggesting new features
Helping us to write user manuals and tutorials (see some examples).
Translating the user interface and documentation
Promoting the project

If you are a programmer you can contribute with the things above, and also with NCL Composer's source code. See the following pages for more information:

You can extend NCL Composer:

Developing your own plugin

If you have created (or are creating) a plug-in to NCL Composer, let us know to include at the plug-ins page.

NCL Composer project file specification

2017-02-03T16:31:17-03:00

NCL Composer project file specification

In its current version (0.1.x) a project file in NCL Composer is a unique file with extension .cpr. This file is a text file, compressed through a ZIP algorithm.

The file is composed of a set of sections. Each section delimiter is started with #SECTION_NAME.

The first section (the header of the file) is the #COMPOSER_PROJECT section.

The second section is the #COMPOSER_MODEL section, that will contain a serialized version of the internal model of the NCL Composer.

Following this, there will be N #COMPOSER_PLUGIN_DATA sections. Each #COMPOSER_PLUGIN_DATA will contain specific data of the plug-in.

#COMPOSER_PROJECT name="project-example" version="0.1"
#COMPOSER_MODEL
...
#END_COMPOSER_MODEL
#COMPOSER_PLUGIN_DATA "br.puc-rio.telemidia.textual"
..
#END_COMPOSER_PLUGIN_DATA
...

Plug-in API

The IPlugin API defines a signal that can be called when a plug-in wants to save some data. This way, when creating a plugin, developers can call the core to save its specific data through a code similar to:

  QByteArray data;
  ...
  // Fill data variable
  ...
  emit setPluginData(data); // call core to save the specific plug-in data.

Moreover, when a project is closed, the core will call a specific slot from the plugin API:

  bool saveSubsession();

You need to re-implement this method if you want to save the specific plug-in data when the project associated to that plug-in is closed.

I typical implementation of this method is:

  bool MyPlugin::saveSubsession()
  {
    QByteArray data;
    ...
    // Fill specific plug-in data in the data variable
    ...
    emit setPluginData(data); // call core to save the specific plug-in data.
  }

Submitting a patch to NCL Composer

2017-02-03T16:31:17-03:00

Submitting a patch to NCL Composer

You can submit a patch directly to our Mailing List (go to contact page for more information).

The easiest way to create a patch is using the git features. We recommend you create a new branch and hack whatever you want in this local branch. This way, you can commit your changes locally and even keep track of your local changes easily.

Let's say you want to changes some code in the composer-core project. First you need to clone the repository and then create your own local branch:

$ git clone git://git.telemidia.puc-rio.br/composer-core.git
$ cd composer-core
$ git checkout -b myfix_to_composer

Now, you can change whatever you want and commit your changes to your myfix_to_composer local branch.

When you are done, you can create a new patch with the following command:

$ git format-patch master --stdout > mypatch.patch

Now, send us this mypatch.patch file.

You can also, send this patch directly from git, using git send-email command:

$ git send-email --to=composer-dev@telemidia.puc-rio.br mypatch.patch