====================================
                              mCtrl Project Readme
                         <http://mctrl.sourcefoget.net>
                      ====================================


What is mCtrl
=============

mCtrl is C library providing set of additional user interface controls for
MS Windows, intended to be complementary to standard Win32API controls from
USER32.DLL and COMCTL32.DLL.

API of the library is designed to be similar to the Win32API. I.e. after window
class of particular control is registered with corresponding initialization
function, the control can be normally created with the Win32API's CreateWindow()
or CreateWindowEx() functions and controlled with SendMessage().


License
=======

mCtrl itself is covered with the GNU Lesser General Public License 2.1 or
(at your option) any later version. See file COPYING.lib for more info.

In brief, this generally means that:

   * Any program or library, even commercial, covered with any proprietary
     license, is allowed to link against the mCtrl's import libraries and
     distribute MCTRL.DLL along with the program.

   * You can modify MCTRL.DLL (or its source code) and distribute such modified
     MCTRL.DLL only if the modifications are also licensed under the terms of
     the LGPL 2.1 (or any later version); or under the terms of GPL 2 (or any
     later version).

Source code of all examples, i.e. contents of the directory 'examples' within
the source package (see below), are in public domain.


Getting mCtrl
=============

You can always get the latest version and most actual information on project
webpages:

    * http://mctrl.sourceforge.net
    * http://sourceforge.net/projects/mctrl

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 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 hoested on github:

    * http://github.com/mity/mctrl


Using mCtrl
===========

If you have the pre-built package, using mCtrl is as easy as using any other
DLL.

Header files are located in 'include\mCtrl' directory. You should instruct
your C/C++ compiler to search for header files in the 'include' directory and
use the 'mCtrl' in your preprocessor #include directives, e.g.:

    #include <mCtrl/version.h>

Import libraries are located under the 'lib' (32-bit libs) and 'lib64' (64-bit)
subdirectory:

    * libmCtrl.a for gcc-based toolchains (e.g. mingw, mingw-w64)
    * mCtrl.lib for MSVC

And finally deploy your application with the MCTRL.DLL which is located
in the 'bin' (32-bit binaries) and 'bin64' (64-bit) subdirectories in
the prebuilt package.

Documentation for application developers is bundled within the pre-built
package, or you can also find the documentation online:

    http://mctrl.sourceforge.net/doc.php


Building mCtrl from Sources
===========================

Disclaimer: If you want to just use MCTRL.DLL you should probably stick with
the pre-built package.

Primary development platform for mCtrl project is mingw-w64 (I use the builds
made by mingw-builds projects) and MSYS. Assuming you have setup the environment,
and have the mCtrl sources then the build should be as easy as running 'make'
from the root directory:

    $ make

Or, especially in case your mingw-w64 is built as a cross-compiler, you may
find useful a script wrapping the Makefile. The following command shows its
options:

    $ scripts/build.sh --help

MS Visual Studio solution (usable with the free Express edition) can also be
found under the contrib subdirectory. However note this may be slightly out
of date and (especially if you get development sources) you may need to update
it to reflect latest changes to the Makefile, especially ensure the solution
includes all mCtrl sources.


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:

    * http://github.com/mity/mctrl/issues