Development

0. Welcome to Minibloq's Developers Guide
This guide explains how to modify Minibloq. It's still under construction, but it will include useful data for developers, translators, designers (whom may want to change Minibloq's graphics) and advanced users.


1. How to translate Minibloq
Since the version v0.81.Beta, Minibloq supports internationalization (i18n) / localization (i10n). This brief tutorial explains how to translate Minibloq, using open source tools. Before start translating, you will need to:
  1. Download the last Minibloq version from the downloads page.
  2. Install Minibloq in your computer. For development purposes, it's highly recommended to install it in a directory where you can freely modify files, instead of the default C:\Program Files (or C:\Program Files (x86) folder. For example, in Windows 7, the Program Files folder is protected. So it will be better to install Minibloq elsewhere, in some temporal dir where you can write, copy, delete or edit files without administrative permissions.
  3. Download Poedit from http://poedit.net (we used the version 1.4.6 for all our internal work).
1.1. Translating the GUI
The first thing to be translated is the GUI itself. This task is relatively easy, by following these steps:
  1. Every language has an international 2 letters code, called ISO 639-1. You will need to find your language code first. You can go to this link for that:  http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
  2. In Minibloq's installation path (for example C:\Program Files (x86)\Minibloq.v0.81.Beta), go to the following folder: Components\Minibloq\v1.0\GUI\Texts, and make a copy of the files en.po and en.Metadata.po.
  3. Now rename both new files (the copies you just made) using your 2 letters language code, instead of the English code "en". For example: Supose we are translating to Spanish. The code for Spanish is "es", so you will end with a file named es.po and another named es.Metadata.po (note: the names are case sensitive, so you must take care of using exactly these names).
  4. Open the Metada "po" file (ie, en.Metadata.po for English, es.Metadata.po for Spanish, etc.) with a raw text editor (in Windows you can even use the Notepad) and change the "en" code in the following line by your new language code:

     msgid "en.Name"
    

    For example, for Spanish, you will end with a line like this:

     msgid "es.Name"
    
  5. Now open the Metadata file with Poedit and change the language name ("English" in this case) by the new language name, but written in the new language itself. For example, for Spanish, it will be "Español":
  6. In Poedit, press the Save button (or go to the menu File->Save). This will not only save the .po file, but will also generate the .mo file, which is the compiled, portable, OS independent file that Minibloq will need to work (but please don't delete the .po file, it will be deployed with Minibloq also!)
  7. Now open the file xx.po with Poedit (where xx is your language code). In our example with Spanish, it will be the es.po file. Here, you can start translating each text string with the Poedit software. Poedit have, among other features, support for nearly any charset out there. Here is a screenshot with the Spanish file:
  8. Every time you advance with the translation, it's good to press the save button. As before, it will generate the .mo file also. Once you finish, you will have for files: xx.Metadata.po, xx.Metadata.mo, xx.po and xx.mo (where "xx" is your language code).

  9. Now you can test the new language files without restarting Minibloq. Just go to the View->Properties menu and press the Reload languages button. If everything is fine, your new language must be listed in the Language combobox:

1.2. Translating blocks' tooltips
Now let's translate the tooltips for the blocks. As Minibloq is modular and every user can add his own blocks, each block has its own tooltip files. These files are located in the subdir Doc of each block directory (the blocks directories are here: Components\Minibloq\Lib\CPP\Blocks). So, inside each Doc subdir you will find standard .po files that can be translated easily with Poedit, and saved to .mo. You just need to open them with Poedit, change the tooltip string and save it. Here is a screenshot of Poedit with a .po file:

 1.3. Translating help files
The help files do not involve any special program or procedure to be translated. They are just plain HTML files, and they can be edited and translated with any decent HMTL editor. There are only three important things regarding help files:
  1. You must keep the names of the files, in English, just as they are now.
  2. You will need to add the directory with the help files for your language, even if you don't translate them. If you don't do this, Minibloq may show an error dialog box when you select your language or  when you start the application. If you will not translate the files, our advice is just to copy the English help files directory (called simply "en"), and renaming it. The name must be the 2 letters code (ISO 639-1) mentioned above.
  3. If you translate the files, try to use a plain text editor, or a good HTML editor which does not add overhead, nor hidden characters.
The help files are in the following Minibloq's subdir: Components\Minibloq\v1.0\Doc


2. Changing blocks' images
All the images belonging to the blocks can be changed by the user. Every block has a subdirectory called Images, inside its own dir (all the blocks directories are in Components\Minibloq\Lib\CPP\Blocks subfolder). For example, this is the bool constant "True" image (Components\Minibloq\Lib\CPP\Blocks\bool.020.0010.ConstantTrue.CPP.v1.0):
The images are provided in PNG format, with transparent background. The Source.svg file is the SVG (made with Inkscape) which in general contains all the vectorized images, which can be edited then exported as PNG (this can also be made with the Inkscape Export function). The easiest way to change images is to overwrite the provided images with a new one, without changing the name. Then you will need to reload blocks (with the Reload blocks button in the Hardware window). There are more complex blocks with more images, you can dig in the block XML definition files (with extension .block). We hope to improve this documentation in the future.


3. Changing GUI theme images
Minibloq will become more and more customizable in the next versions. But right now, it's possible at least to change the images in the main GUI (the images belonging to menues and to the quick toolbar). It's easy: Just go to the following subdir (in Minibloq's installation path):

Components\Minibloq\v1.0\GUI\Images

There you will find Theme subfolders (named Theme0, Theme1, and so on). Minibloq loads the images in the Theme0 subfolder. To change the images, just overwrite the current onces with your new images. You will need to provide images with similar resolution, all in PNG format (with transparent background):

4. Adding user defined blocks
Minibloq loads the blocks at runtime. All the blocks are defined in XML files. In the future, we plan to document better how to add custom blocks. Also, the block syntax will still evolve (there is still a lot of work to do). But even now, it's possible for the users to write their own custom blocks. Although we are working hard in Minibloq's documentation, by now, we can give here just an example. Special thanks to Andrew Lawrance who contributed a lot to the following example:

4.1. Example: Adding a delayMicroseconds() block
Let's add a new block to use the delayMicroseconds() function from the Arduino API. To do this, we will start from a block that already exists. This block is very similar to the one we want to create: It's the delay block. So we just need to follow these small steps:
  1. Make a copy of the  folder which belongs to the delay block  (you will find it in the Components\Minibloq\Lib\CPP\Blocks subfolder, inside Minibloq's installation path). The delay block folder's name is action.010.0040.delay.Arduino.v1.0
  2. Rename the new folder. For example, this may be a good name:  action.010.0050.delay_us.Arduino.v1.0
  3. Inside that folder, you will find the file main.block. Open it with a raw editor (like Notepad++, for example).
  4. Change the following line:
     delay

    by this:
     delayMicroseconds

  5. Now change this another line (and then save the file):
     delay

    by this:
     delayMicroseconds

  6. Now you have to tell Minibloq which boards will load this block when they are selected (every block can be compatible or incompatible with a board, and is the Developer's task to decide this). For this, you will need to create an empty  txt file (in future versions these files will have some content, but right now they are just empty raw text files) named with the same name as the folder where you created the new block, followed by the .rel extension. In our example, this file will be named action.010.0050.delay_ms.Arduino.v1.0.rel
  7. Copy that file to the Matrix subdirectories of all the boards (or targets) that you want to load that block. For example, to add the block to the Arduino Uno board, you will need to copy that file in the  following subdirectory (inside Minibloq's installation path): Components\Minibloq\Lib\CPP\Targets\ArduinoUNO_Arduino.v1.0\Matrix
  8. Now select your board. If you have already selected it, just press the Reload blocks button in the Hardware window (this window can be made visible with the menu View->Hardware). Your Actions picker must be something like this (please note the two "delay" blocks):
Note that we did not change the block's images (for the block itself, or for the picker), nor the structure of the block (regarding parameters, for example). Even the tooltip was untouched. This is just a very basic example, now you can dig into the XML structure of the blocks, and as Minibloq does not require to reinitialize the application, you can quickly see the changes of your block using the Reload blocks button. We will improve the blocks' XML documentation when the syntax becomes more finished, but by the moment, we encourage you to take a look to the XML definitions of more complex blocks, such as the while block (in the action.010.0010.while.CPP.v1.0 subdir), the buzzer (action.020.0050.Buzzer.Arduino.v1.0) or the Motor block (action.020.0060.Motor.Arduino.v1.0).


5. Adding hardware
The current Minibloq version (v0.81.Beta) does not support (yet) the addition of new hardware without recompiling it. But this is just a temporal situation. We are working ot have the multi-hardware subsystem functional for the next version (perhaps it will be still a simplified system, but we will continue working on the improvement of this absolutely fundamental part of the program).


6. Modifying and compiling Minibloq
6.1. Getting the source code
You can download the sources: http://minibloq.td-er.nl/Minibloq.v0.81.Beta.UP2.Sources.zip. Please note that this file only includes the sources. It should be very handy to first decompress a full Minibloq (from the Donwloads page) and then decompress the sources over it. If you do this, please don't use an installation directory inside Program Files (or Program Files (x86) since you may experiment permissions problems when developing.

6.2. Compiling Minibloq for Windows
We worked a lot to deploy not just Minibloq itself, but a complete portable open source IDE as well, ready to run. It's a modified version of Portable Code::Blocks, with a precompiled wxWidgets library (and a lot of other things, like the Irrlich open source game engine -you can take a look to the dir sdk inside Code::Blocks' dir structure-). This IDE runs under Windows (XP, Vista and 7) and you only need to decompress it and run the CbLauncher.exe (please note this: CbLauncher.exe is the ONLY exe there that will actually work right when you run de IDE). The complete IDE is here:

http://multiplo.org/files/soft/CodeBlocks-RG.v0.1.zip

Once you have the IDE, you just need to open the workspace (Minibloq.v1.0.workspace) deployed with Minibloq's sources and select the Release target (don't forget that). Finally, you will need to do a Rebuild of the Minibloq project (there are 2 projects in the workspace: Minibloq itself, and MinibloqRun, but this last one is just a loader that helps to make Minibloq portable, nothing else, and it's precompiled in this distribution). Minibloq should compile with 0-Errrors and 0-Warnings in about 2 minutes (depending on your machine). Please be sure not to change the target (there are two targets: Release and Debug, always use Release, because the "Debug" target one does not work).

6.3. Compiling Minibloq for GNU/Linux (Ubuntu)

This step by step guide was first written by Juan Pizarro, from doingIT Informática:

0. Please download the latest Minibloq for GNU/Linux from the Downloads page and uncompress them in the dir you will use for development.

1. Then download Minibloq's sources, and uncompress them over the full Minibloq installation from step 1.

2. Install as root libwxgtk2.8-0 (this is a dependency necessary for Code::Blocks):

apt-get install libwxgtk2.8-0

3. Download Code::Blocks from: http://www.codeblocks.org/downloads/26#linux. Depending on your hardware, you should download one of these files:
  • codeblocks-10.05-1-debian-i386.tar.bz2
  • codeblocks-10.05-1-debian-amd64.tar.bz2

Now please uncompress the file that you have downloaded:

tar xf codeblocks-10.05-1-debian-i386.tar.bz2
tar xf codeblocks-10.05-1-debian-amd64.tar.bz2

4. In the folder i386 or amd64 (accordingly to your hardware), install the .deb packages as root:

dpkg -i *.deb

5. Download the file wx-292.tar.bz2 from https://docs.google.com/open?id=0B3Y4juLvYMY1dUhEalNQTUlEaWc.
(sources are here: wxWidgets-2.9.2.tar.bz2 - http://sourceforge.net/projects/wxwindows/files/2.9.2)

6. Uncompress that file:

tar xf wx-292.tar.bz2

7. Rename it as wx. Now you should have the directory wx at the same level as the directory Minibloq.v0.8.Beta.Sources. This is necessary, since in the .cbp files the references are like these:

Minibloq.Linux.Custom-wx.i386.v1.0.cbp
-I../wx/i386/usr/lib/wx/include/gtk2-unicode-2.9-minibloq
-I../wx/i386/usr/include/wx-2.9-minibloq
<Add directory="../wx/i386/usr/lib" />

Minibloq.Linux.Custom-wx.amd64.v1.0.cbp
-I../wx/amd64/usr/lib/wx/include/gtk2-unicode-2.9-minibloq
-I../wx/amd64/usr/include/wx-2.9-minibloq
<Add directory="../wx/amd64/usr/lib" />

8. Now you should be able to open the .cbp (Code::Blocks project) file with Code::Blocks and compile Minibloq. You should select the project file according to your system:

Minibloq.Linux.Custom-wx.amd64.v1.0.cbp

or

Minibloq.Linux.Custom-wx.i386.v1.0.cbp