cumbia ui make. A tool to configure a Qt project with cumbia widgets
cuuimake is a command line tool that can be found and built under the qumbia-apps/cuuimake/ folder.
Installation
- git clone https://github.com/ELETTRA-SincrotroneTrieste/cumbia-libs.git
- cd cumbia-apps/cuuimake/
- qmake
- make
- make install
The final command will install cuuimake under /usr/local/bin/
An xml configuration file describing predefined options and keywords is installed under /usr/local/share/cuuimake/cuuimake-cumbia-qtcontrols.xml This file contains
- file name filters to find C++ sources (default: *.cpp, *.h, *.ui, ui_*.h)
- the name of the available factories (for cumbiapool, cumbiatango and cumbiaepics) and the associated
- the name of the classes that must be configured with cumbia. Constructor invocation must be extended with additional parameters.
cuuimake command shortcut
If the cumbia utilities have been installed from the top level directory qumbia-apps, then cuuimake can also be executed with the following shortcut
cuuimake stages
cuuimake task is accomplished in several stages:
- Clean [optional] make clean is run first and ui_.*.h files are removed, so that they are regenerated and re-expanded.
- Qmake [optional] if the option is enabled [–qmake] qmake is run as a first step
- Analysis of the files in the project directory to find cumbia object declarations
- Expand the files are expanded so that the cumbia objects constructor is appropriately invoked with additional parameters
- Uic Qt uic is executed on the ui to generate the ui_xxx.h file.
- Make the make program is run to compile the application [option: –make]
Other cuuimake modes:
- Help the program has been invoked with the –help option
- Info the program is printing informative content
Personalize cuuimake
Running cuuimake with the –configure option allows to store some settings permanently in your home directory by means of the Qt QSettings system:
Reply only with "y" or "n" to the y|n questions (without enter) and with a digit + enter to the -jN option.
cuuimake –show-config shows the current configuration
cuuimake –show-config with additional parameters shows the options that would be applied if those options were given:
Using cuuimake
qmake
Qt qmake must be run before anything else.
Note: cuuimake –qmake will run cuuimake including qmake as the first stage. –qmake option can be permanently enabled through the cuuimake –configure wizard.
After qmake, cuuimake must be run from the project top level directory. Alternatively, run cuuimake –qmake or enable qmake option with cuuimake –configure.
cuuimake
run cuuimake after qmake has been successfully executed, from the same (top level) directory where qmake has successfully completed.
This stage loads settings from cuuimake configuration files to know what are the classes that need to be expanded, finds the usage of those classes within the source files and expands them according to either CumbiaTango, CumbiaEpics or CumbiaPool is used. Projects with mixed usage of CumbiaTango, CumbiaEpics or CumbiaPool are not supported by cuuimake. If cumbiaappwizard application has been used to generate the app skeleton, the project will be easily analyzed and expanded by cuuimake.
As you can see in the last analysis line, the detected mode is cumbiatango and so the expansion involves adding CuTReaderFactory, CuTWriterFactory and CumbiaTango keywords and variable names to the source files. While the user interface file (.ui ) does not change or is not removed, cuuimake will not process the source files again.
cuuimake with Qt designer "promoted widgets"
As shown in the picture below, with Qt designer you can promote a base widget to a custom widget. If the promoted element is a cumbia widget, cuuimake must expand its constructor as well.
The promoted class name is MyAttributeHistoryTree, which is not part of the library, is defined in the myattributehistory.h header and implemented in the myattributehistory.cpp file. If a promoted widget is detected by cuuimake in the ui file, its definition is searched among the files in the project. If the definition is found and recognised as a cumbia object, cuuimake is able to perform the necessary constructor expansion.
If cuuimake is unable to automatically expand the custom class, a build error will occur. To explicitly tell cuuimake that a widget needs to be expanded, you must create a file cuuimake-historytree.conf.
cuuimake will use all files with a name matching the pattern "cuuimake[.*].conf to apply additional expansion to the classes therein listed</strong>. Edit the <em>cuuimake-historytree.conf</em> text file and add the following line: @code MyAttributeHistoryTree,cumbiatango,CumbiaTango *,CuTReaderFactory \endcode Comment lines are allowed and start with a '#'. Comma separated fields: -# class name, MyAttributeHistoryTree -# "engine", or "factory" one of: <em>cumbiatango</em>, <em>cumbiaepics</em>, <em>cumbiapool</em> -# list of <strong>qualified</strong> parameter type names that have to be inserted into the cumbia-qtcontrols object constructor (*<strong>qualified</strong> class names*, as defined in the main class header file, if the project has been generated with <em>qumbiaappwizard</em>) For example, if <em>qumbiaappwizard</em> creates a mycumbiatangoapp.h file and a class Mycumbiatangoapp that defines cumbia related attributes like this: @code private: CumbiaTango *cu_t; CuTReaderFactory cu_tango_r_fac; CuTWriterFactory cu_tango_w_fac; \endcode and the custom widget has constructors defined as follows: @code MyAttributeHistoryTree(QWidget *_parent, Cumbia *cumbia, const CuControlsReaderFactoryI &r_fac); MyAttributeHistoryTree(QWidget *parent, CumbiaPool* cu_poo, const CuControlsFactoryPool& f_poo); \endcode the <em>Qt designer</em> would instantiate MyAttributeHistoryTree like this: @code widget = new MyAttributeHistoryTree(Mycumbiatangoapp); \endcode within the <em>src/ui_mycumbiatangoapp.h</em> file, which would result in an error. The line in the file <em>cuuimake-historytree.conf</em>, placed at the top level project directory, alongside the .pro file, tells the <em>cuuimake</em> to <em>expand</em> the MyAttributeHistoryTree constructor inserting the <em>cu_t, cu_tango_r_fac and cu_tango_w_fac parameters after *Mycumbiatangoapp</em> (the parent widget): @code // widget = new MyAttributeHistoryTree(Mycumbiatangoapp); // expanded by cuuimake v.0.1 widget = new MyAttributeHistoryTree(Mycumbiatangoapp, cu_t, cu_tango_r_fac); \endcode If <em>qumbiaappwizard</em> is used to create an <em>epics</em> project, the main class header file contain something like this: @code private: Ui::Cuepexample *ui; CumbiaEpics *cu_e; CuEpReaderFactory cu_ep_r_fac; CuEpWriterFactory cu_ep_w_fac; \endcode and if we promoted a QWidget to a <em>MyAttributeHistoryTree</em>, the lines of the needed <em>cuuimake-historytree.conf</em> file would have to be like this: @code MyAttributeHistoryTree,cumbiaepics,CumbiaEpics *,CuEpReaderFactory \endcode <h3>cuuimake and make</h3> It is possible to run <em>cuuimake</em> immediately followed by <em>make</em> choosing one of these options: \li running <em>cuuimake –make</em> \li configuring <em>cuuimake</em> with <em>cuuimake –configure</em> and answering <em>y</em> to the "make" question \li running <em>cuuimake -jN</em>, where N is the <em>make -j</em> option for pipelined compilation. <h3>Cleaning ui_.*.h files</h3> <em>cuuimake –clean</em> runs <em>make clean</em> and removes all ui_.*.h files under the <em>ui</em> directory. (defined in the <em>cuuimake-cumbia-qtcontrols.xml</em> global configuration file under *<srcdirs><uihdir>*, "ui" by default). This is useful if you want the ui_.*.h files produced by Qt uic to be regenerated and re-expanded. For example, if you modify the cuuimake.*.conf file, you need to run cuuimake –clean to have the ui_.*.h files refreshed.
To remove the ui_*.h files and proceed with the following stages, run cuuimake with the –pre-clean option instead.
