0. Welcome to miniBloq's Developers Guide
1. How to translate miniBloq
The first thing to be translated is the GUI itself. This task is relatively easy, by following these steps:
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):
Under construction: I will soon document the new miniBloq v0.82 powerful XML backend. Now miniBloq loads the blocks at runtime. All the blocks are defined in XML files, so it's easy to add new user defined blocks.
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:
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
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.
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:
- Download the last miniBloq version from the downloads page.
- 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.
- Download Poedit from http://poedit.net (we used the version 1.4.6 for all our internal work).
- 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
- In miniBloq's installation path (for example C:\Program Files (x86)\miniBloq.v0.8x), go to the following folder: mbq\v0.82\GUI\Texts, and make a copy of the files en.po and en.Metadata.po.
- 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).
- 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"
- 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":
- 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!)
- 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:
- 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:
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).
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 inside the blocks directory). 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:
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 inside the blocks subfolder). For example, this is the bool constant "True" image (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):
mbq\v0.82\GUI\Images
mbq\v0.82\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
Under construction: I will soon document the new miniBloq v0.82 powerful XML backend. Now miniBloq loads the blocks at runtime. All the blocks are defined in XML files, so it's easy to add new user defined blocks.
5. Adding hardware
Under construction: I will soon document the new miniBloq v0.82 powerful XML backend. Now miniBloq loads the boards and hardaware targets at runtime. All the boards are defined in XML files, so it's easy to add new user defined hardware.
6. Modifying and compiling Minibloq
6.1. Getting the source code
You can download the sources from the repository in GitHub:
https://github.com/miniBloq/v0.82
You can both replicate the repository, or use the Downoad ZIP button there.
https://github.com/miniBloq/v0.82
You can both replicate the repository, or use the Downoad ZIP button there.
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.Windows.32bits.v0.82.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).
http://multiplo.org/files/soft/CodeBlocks-RG.v0.1.zip
Once you have the IDE, you just need to open the workspace (Minibloq.Windows.32bits.v0.82.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
