What is mCtrl
mCtrl is a C library providing set of additional user interface controls for
MS Windows, intended to be complementary to the standard Win32API controls from
The API of the library is designed to be similar to the Win32API. I.e. after
a window class of a control is registered with corresponding initialization
function, the control can be normally created with the Win32API's functions
CreateWindowEx() and controlled with
You can always get the latest version and most actual information on project home site:
There are usually two packages for each release version available:
mCtrl-x.y.z-bin.zip: pre-built binary package
mCtrl-x.y.z-src.zip: source package
The pre-built package contains 32-bit as well as 64-bit binaries of
and examples, and also documentation for application developers. The source
package is direct export of source tree from version control system repository.
The current code (possibly untested and unstable) can also be cloned from git repository hosted on github:
The pre-built release package has the following directory structure:
mCtrl-x.y.z/ | AUTHORS.md # List of authors contributing to the project | CONTRIBUTING.md # Info how to contribute to the project | COPYING.lib # GNU Lesser General Public License | README.md # This file | +- bin/ # 32-bit binaries | | mCtrl.dll # MCTRL.DLL | | example-*.exe # Pre-built examples | | | +- debug-gcc/ | | mCtrl.dll # Debug build of MCTRL.DLL (built with gcc) | | | +- debug-msvc/ | mCtrl.dll # Debug build of MCTRL.DLL (built with Visual Studio) | mCtrl.pdb # Visual Studio debug info | +- bin64/ # 64-bit binaries | | mCtrl.dll # MCTRL.DLL | | example-*.exe # Pre-built examples | | | +- debug-gcc/ | | mCtrl.dll # Debug build of MCTRL.DLL (built with gcc) | | | +- debug-msvc/ | mCtrl.dll # Debug build of MCTRL.DLL (built with Visual Studio) | mCtrl.pdb # Visual Studio debug info | +- doc/ # Reference manual | *.html | +- examples/ # Examples | CMakeLists.txt # CMake recipe for building the examples | *.c; *.h; *.rc # Source files of the examples | +- include/ | | mctrl.h # All-in-one public header (includes all mCtrl/*.h) | | | +- mCtrl/ | *.h # mCtrl public headers | +- lib/ # 32-bit import libraries | libmCtrl.dll.a # Import library for gcc | mCtrl.lib # Import library for Visual Studio | +- lib64/ # 64-bit import libraries libmCtrl.dll.a # Import library for gcc mCtrl.lib # Import library for Visual Studio
Using mCtrl is as easy as using any other DLL, just tell your compiler and linker where it can find mCtrl headers and libraries.
Note you should instruct your C/C++ compiler to search for header files in
include directory and use the directory
mCtrl as part of preprocessor
#include directives, e.g.:
#include <mCtrl/dialog.h> #include <mCtrl/treelist.h>
Building mCtrl from Sources
Disclaimer: If you want to just use
MCTRL.DLL you should probably stick with
the pre-built package.
To build mCtrl yourself from the source package or cloned git repository, first of all you need to use CMake 3.1 (or newer) to generate project files, Makefile or whatever the development tool-chain of your choice expects.
Build with Mingw-w64
It's recommended to use out-of-source-tree builds, so create e.g. a directory
build in the main mCtrl directory. (If you build in directory located
elsewhere, replace the
.. in the following instructions with the path
pointing to the root mCtrl directory.)
To build with MSYS + mingw-w64 + Make:
$ mkdir build $ cd build $ cmake -G "MSYS Makefiles" .. $ make
To build with MSYS + mingw-w64 + Ninja:
$ mkdir build $ cd build $ cmake -G "Ninja" .. $ ninja
To build within MSYS2, make sure you have these MSYS2 packages installed:
mingw-w64-i686-cmake(for 32-bit build)
mingw-w64-x86_64-cmake(for 64-bit build)
Then start MSYS2 shell with
respectively and follow the same instructions as above for MSYS +
mingw-w64 + Make.
Note you may need to specify path to
gcc if you want to use a different gcc
version than the one in your
$PATH, e.g. if you have multiple mingw-w64
variants installed, one targeting 32-bit and one 64-bit build.
You may do so by setting the variable
CC prior using CMake. CMake is smart
enough to derive paths to the other tools like a linker or a resource compiler
Build with Microsoft Visual Studio 2017 (or newer)
Visual Studio 2017 and newer supports CMake build system directly:
- Start Visual Studio 2017.
- In menu File, choose submenu Open and Folder.
- In the open dialog, navigate to mCtrl main folder and open it.
- In menu CMake, choose Build all.
Build with Older Version of Microsoft Visual Studio
To build with older Microsoft Visual Studio (versions 2013 and 2015 are known to work), you have to generate project files manually:
$ mkdir build $ cd build $ cmake -G "Visual Studio 12 2013" .. # MSVC 2013, 32-bit build $ cmake -G "Visual Studio 12 2013 Win64" .. # MSVC 2013, 64-bit build $ cmake -G "Visual Studio 14 2015" .. # MSVC 2015, 32-bit build $ cmake -G "Visual Studio 14 2015 Win64" .. # MSVC 2015, 64-bit build
Then open the generated solution file
build/mCtrl.sln in Visual Studio and
build the target
Unfortunately, for older MSVC versions, CMake does not support generating projects targeting multiple architectures. Therefore, to build both 32 and 64-bit binaries, you have to generate project files or Makefiles twice and build them separately, in dedicated directories.
Other CMake generators may or may not work. If they do not, then one or more
CMakeLists.txt files within mCtrl directory hierarchy may need some tuning.
$ cmake --help
and refer to CMake documentation to learn more about CMake, its options and capabilities.
After the Build
After the building, consider running a mCtrl test-suite to verify correctness of your build. The test suite, as well as some examples demonstrating mCtrl, are built as part of the mCtrl build process.
mCtrl itself is covered by the GNU Lesser General Public License 2.1 or
(if you choose so) any later version. Refer to the file
more information about licensing terms.
Some source files and libraries incorporated into mCtrl may have different (but compatible) licensing terms and some may be put into the public domain:
- Examples (
examples/*): Public domain
- Unit tests (
tests/*.c): Public domain
- 3rd party code:
- Acutest (
lib/acutest/): MIT license
- c-reusables (
lib/c-reusables/): MIT license
- HSLuv-C (
lib/hsluv-c/): MIT license
- Acutest (
If you encounter any bug, please be so kind and report it. Unheard bugs cannot get fixed. You can submit bug reports here:
Please provide the following information with the bug report:
- mCtrl version you are using.
- Whether you use 32-bit or 64-bit build of mCtrl.
- OS version where you reproduce the issue.
- As explicit description of the issue as possible, i.e. what behavior you expect and what behavior you see. (Reports of the kind "it does not work." do not help).
- If relevant, consider attaching a screenshot.
- If relevant, some code reproducing the issue can be vital. Ideally in some
of these forms:
- a complete source code which can compile as a standalone C or C++ program;
- a patch or pull request to be applied to one of the examples in mCtrl source tree;
- or (if it is not overly long) as a C function (or few functions) which can replace whole function (or few functions) in one of those examples.