Repository files navigation

Bindings for the Qt5 Framework usingbindgen.

• Project Goals
• Installation
  • Additional development dependencies
• User perspective
  • Sample Crystal-Qt5 code
• Developer perspective
  • Generating the bindings
  • Naming scheme
  • (Re)generating all Qt5 binding versions
  • (Re)generating a specific Qt5 binding version
  • Future things to do
• Platform Support
• Contributing
  • Contributors
• License
  • A note on Qt's license

• Just Works™ - Drop the dependency into a project, and use it
• Providing an API that feels native to Crystal
• Focus on the GUI components (i.e.QtCore,QtGui,QtWidgets)

If you just want to develop a Crystal app which uses Qt5, use themaster-ready-to-usebranch. It contains pre-built/pre-generated bindings for certain platform and Qtcombinations. If that branch contains the pre-generated bindings for your platform,which you can verify in thesubdirectoryext/,you won't need bindgen at all.

dependencies:qt5:github:Papierkorb/qt5.crbranch:master-ready-to-use

If you want the bindings to be generated for the current system, or if you wantto generate bindings for new platform and Qt combinations, use the masterbranch:

dependencies:qt5:github:Papierkorb/qt5.crbranch:master

In any case, your users will be required to have the Qt5 libraries on their systembecause this project defaults to binding to Qt libraries dynamically. (See moreon this under License below.)

Using your system's package manager:

• ArchLinuxpacman -S qt5-base
• Debian/Ubuntu/Devuanapt-get install qtbase5-dev cmake llvm-dev clang libclang-dev libz-dev libstdc++-dev

You also needcmake.

Have a look insamples/!

A shortHello World snippet looks like this:

require"qt5"qApp=Qt::Application.newlabel=Qt::Label.new"Hello from Crystal/Qt!"label.showQt::Application.exec

By default Qt sets the locale to the system locale when an applicationclass (likeQt::Application) is instantiated. However, this causesstdlib Crystal functions liketo_f to behave unexpectedly, e.g.,using a different character as decimal separator (also see the discussionof thisPR).Therefore, in contrast to the behaviour of the C++ classes of Qt,qt5.cr resets the numeric locale to "C" after creating anapplication class instance (this follows anadvice from Qtitself).

If you want to work onqt5.cr itself or you want to generate bindings for newversions, then as mentioned you need to use branchmaster and run thegeneration yourself.

These steps can be followed from a project usingqt5.cr, or from withinqt5.cr itself. For the latter, you can just go tolib/bindgen and dogit checkout master instead of modifyingshard.yml.

Important: For this you'll also have to meet the dependencies of bindgen.

Asqt5.cr supports many different versions of Qt on different platforms,generated bindings follow a naming scheme. The scheme contains 4 componentsas follows:

KERNEL - LIB_C - ARCH - qtVERSION, e.g.linux-gnu-x86_64-qt5.13

Where:

• KERNEL is the OS kernel, e.g.linux,darwin,windows
• LIB_C is the lib C name, e.g.gnu,musl,win32
• ARCH is the architecture, e.g.i686,x86_64,arm
• VERSION is the Qt version, e.g.5.9,5.12,5.15

The naming scheme is not strictly enforced. However, it should always end with-qtVERSION!

Themaster-ready-to-use branch contains a number of prebuilt bindings.The following process was used to build them:

1. Cd into theqt5.cr directory, switch to the master branch
2. Editsupport/generate_bindings.cr and enable all versions for which you wantto generate the bindings
3. Runcrystal support/generate_bindings.cr
4. Commit the files inext/ to themaster-ready-to-use branch

The build process will automatically download, unpack, build, and generate allconfigured versions of Qt5. It'll store the downloaded and unpacked Qt5 versionsto directory calleddownload_cache/.Subsequent invocations of that script will use these cached assets.

The first run may take a long time, and each version of Qt5 will take up about4GB of disk space.

1. Use themaster branch ofqt5.cr in yourshard.yml
2. Decide which version of Qt to use, and build the scheme (See above)
3. Export the binding scheme:export BINDING_PLATFORM=linux-gnu-x86_64-qt5.13
4. If you're not using your system's Qt:export QMAKE=/path/to/qmake
5. Run bindgen as usual:lib/bindgen/tool.sh qt.yml --stats
6. Verify withcrystal spec

• ForwardingqHash() of wrapped types (toObject#hash)
• Integration withLibEvent: Right now, Qt blocks the whole thread.
• The rest of the billion Qt classes of interest
• Everything in theto be done category
• Integration for theQt Designer UI designer
• Integration forQt Linguist
  • Localization/Translation for your applications!
• UI test library, with adapter forspec
  • Also, actual tests - Let's catch whacko bugs right in the CI!
• Automated copy (and adaption) of the Qt documentation, for easy Crystal-specific docs
  • The Qt Docs license should allow this if done correctly

Ready-to-use Qt versions: 5.5 to 5.12

(This list needs updating)

1. Open a new issue on the project to discuss what you're going to do and possibly receive comments
2. Read bindgen'sSTYLEGUIDE.md for some tips
3. Then do the rest, PR and all. You know the drill :)

• Papierkorb Stefan Merettig - creator

The Qt bindings, including the generated and manually-written parts, are subjectto the MPL-2 license. You can find a copy attached of the full license text intheLICENSE file.

This project claims no copyright on theQt framework or of any of itstrademarks, source, or any other assets.

A common misconception is that you have to pay for Qt to use it in closed-sourceapplications.

This project assumes you'll link to Qt dynamically. In this case, you can useQt free of charge including forclosed-source, commercial applicationsunder the terms of theLGPL.

You can build closed-source applications using Crystal, this shard, and Qtfor free.

Note: This section is to combat this misconception, the authors ofqt5.crare in no way responsible to check if the same terms applyin your jurisdiction.