C library providing set of additional user interface controls for Windows, intended to be complementary to standard Win32API controls from USER32.DLL and COMCTL32.DLL.
mCtrl Readme
- Home website: http://mctrl.org
- Main code repo: http://github.com/mity/mctrl
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
USER32.DLL and COMCTL32.DLL.
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
CreateWindow() or CreateWindowEx() and controlled with SendMessage().
Getting mCtrl
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 packagemCtrl-x.y.z-src.zip: source package
The pre-built package contains 32-bit as well as 64-bit binaries of MCTRL.DLL
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:
Using mCtrl
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
the 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:
makemingw-w64-i686-gcc,mingw-w64-i686-cmake(for 32-bit build)mingw-w64-x86_64-gcc,mingw-w64-x86_64-cmake(for 64-bit build)
Then start MSYS2 shell with mingw32_shell.bat or mingw64_shell.bat
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
automatically.
export CC=/path/to/the/desired/gcc
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 ALL_BUILD.
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 Toolchains
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.
Use
$ 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.
License
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 COPYING.lib.md for
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 (
Reporting Bugs
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.