search

amlwwalker / got-qt

A framework for building cross platform GUI interfaces in Go and QML
MIT License
299 stars 14 forks source link

readme

Got-qt GUI Framework

Quick Start!

General Overview

If you are not interested in manual building and general information (everything below here), you can proceed to automated building

More background

This is a framework to make desktop/mobile applications in Go with a GUI written in Qt Qml. Both of these languages are cross platform. Go is an open source programming language, Qt is licensed under LGPL license. In some instances you will need to buy a commercial Qt license - for instance a statically compiled, commercial app, would need a commerical Qt license. The license for my work here however, is under MIT license.

Home Menu Console UI Android

It uses the Material framework from Google for the UI in Qml, and uses Go as a backend. It demonstrates making pages in Qml, interfacing with the backend Go code, and receving messages from the backend. I.e everything you need to build a desktop app, all ready to go.

I built this because I was building desktop apps in Go, with Guis. For every change I made, i had to recompile the go code even if I was just changing the UI code. This takes a long time. It can be sped up, however I wanted to develop my UI faster. I could have used qt-creator, however it was another IDE, I just wanted an easy way to build desktop apps with Go.

So I added hotloading to the qml files. You can download the demo OSX app here.

Watch the youtube video
Please note this is in early stages

What I wanted:

This is a combination of a lot of work done by alot of people around the web. I am very pleased that I have now, what I think, is a very workable framework for building apps cross platform.

Installation

I am assuming you are a Go developer already and have Go installed with your GOPATH set, etc etc... I am using MacOS so I will put steps for that, however I am linking to where to find installation instructions more generally.

I do however hope you are not a Windows developer... Your paths, your consoles, your docker installations... all will have caveats...

Installing QT

You can install QT by following the instructions for regular installation, however in essence :

brew install qt5

This will install the packaged version of Qt. Its a sort of minimal version to get Qt working easily for OSX. However it is not the official version and does not have support for iOS or Android. That's fine as I am using the docker containers to build for other platforms, but it will lead to a minor step you have to take when building for other platforms

Installing Qt Go-Binding

You can install Qt binding by following these instructions, however in essence:

Installing Material theme

Luckily Qt comes with the theme installed! No need to do anything here!

Test everything,

You can run the example code found here, but in essence, put the following in your $GOPATH/src somewhere and run qtdeploy test desktop

package main

import (
    "github.com/therecipe/qt/widgets"
    "os"
)

func main() {
    // Create application
    app := widgets.NewQApplication(len(os.Args), os.Args)

    // Create main window
    window := widgets.NewQMainWindow(nil, 0)
    window.SetWindowTitle("Hello World Example")
    window.SetMinimumSize2(200, 200)

    // Create main layout
    layout := widgets.NewQVBoxLayout()

    // Create main widget and set the layout
    mainWidget := widgets.NewQWidget(nil, 0)
    mainWidget.SetLayout(layout)

    // Create a line edit and add it to the layout
    input := widgets.NewQLineEdit(nil)
    input.SetPlaceholderText("1. write something")
    layout.AddWidget(input, 0, 0)

    // Create a button and add it to the layout
    button := widgets.NewQPushButton2("2. click me", nil)
    layout.AddWidget(button, 0, 0)

    // Connect event for button
    button.ConnectClicked(func(checked bool) {
        widgets.QMessageBox_Information(nil, "OK", input.Text(),
        widgets.QMessageBox__Ok, widgets.QMessageBox__Ok)
    })

    // Set main widget as the central widget of the window
    window.SetCentralWidget(mainWidget)

    // Show the window
    window.Show()

    // Execute app
    app.Exec()
}

If you get a window appear once the compilation completes (it may take a moment) then everything is working and you can continue. If you have any issues, read the wiki page.

Installing this project

Now your environment is ready, to make app development easy, you can use this project Got-qt. For the sake of argument, I am setting an env var for the project name so I can refer to it elsewhere.

prerequisite. So that the instructions are general for all platforms:

At this stage, the application will build and run. It will take a bit of time. If you get the sample app appearing then great, compilation has been successful.

Help/Demo

To see the above process in action, I have added a youtube video here to give you an idea

Read on for how to develop apps efficiently and easily

Using the framework

Reasons to use this

There is a configuration file that tells the application whether to run in hotloading mode. If it is run in hotloading mode, then it will continually monitor changes to its own qml files and update the user interface immediately. Makes for real time development.

My recommended approach is to build your UI using this in QML, then decide how it needs to interface with the Go code (backend). Once you know those requirements, you can add in the listeners in the Go code and have basic interaction with the front end, proving to your self you have two way comms. Use this two way comms to set the needed bridge connections up, but forget about functionality for now. Just confirm you have the commnunication working.

Then, move to building a console UI. There is a demonstration console UI using the amazing gocui. Its a very straight forward way of building great console applications in Go. I recommend this for a few reasons:

The directory cuiinterface shows how this decoupling of the console UI works. Whats great is because nothing else knows about anything in this directory, it won't get compiled into the application when the GUI is compiled. I recommend this same structure for all your UIs (i.e each having its own directory and nothing else knows about it).

Once the console UI you have built demonstrates the functionality required by the go code, you can then wire up your GUI to the same functions (as the two UI's are just top level interfaces to the backend), and save yourself a lot of compilation time.

Steps

Development

  1. In config.json, make sure that hotloading is set to true
    • Please Note hotloading must be disabled when in production mode and on mobile devices
  2. Make sure you have run packr in the qt/ directory Whenever a change to config.json is made
  3. Run the application with GOPATH/src/$USER/$PROJECTNAME/deploy/darwin/got-qt/Contents/MacOS/got-qt
  4. Navigate with your editor of choice to qml/ - this is where all the UI files are kept.
  5. For now you will be editing loader.qml. This file is configured for hotloading. loader-production.qml is for when the code is to be compiled into the application for deployment. This is necessary because the finder app runs under a different user space to you.
  6. Start editing loader.qml. You will see the UI update as you save.
    • You can edit any of the files under pages/elements and they will be updated automatically.
    • Notice on occasion restarts of the app (but not recompilation) will be required if you break the qml it cannot rebuild it. Just quit and restart easy.

NOTICE If you import new libraries into your qml, then in this case a recompile will be required as those libraries won't have been compiled into the application, this only needs to happen once per new library imported however. Shouldn't be too frequent.

Production

  1. When you are ready for production:
Relative:
ListElement { title: "Contacts"; source: "pages/_contactsPage.qml" }
ListElement { title: "Files"; source: "pages/_filelistPage.qml" }
ListElement { title: "Downloads"; source: "pages/_downloadsPage.qml" }
Qrc:
ListElement { title: "Contacts"; source: "qrc:/qml/pages/_contactsPage.qml" }
ListElement { title: "Files"; source: "qrc:/qml/pages/_filelistPage.qml" }
ListElement { title: "Downloads"; source: "qrc:/qml/pages/_downloadsPage.qml" }

(this step will in time be improved, its a bit annoying to have to do with a find/replace, but ListElements can't have dynamic paths in qml)

Cross Compilation

Using therecipe/qt tools and using docker, its very easy to cross compile for different platforms, but in essence:

docker pull therecipe/qt:windows_32_shared

qtdeploy -docker build windows_32_shared

NOTICE: I have only cross compiled for windows and android, but the steps should be the same for other platforms if you have docker installed.
NOTICE: When cross compiling, to be in a terminal session where you did not run export QT_DIR=/usr/local/opt/qt first

Device Specific Setup

Android

In the android/ directory there is the configuration to setup the android app. There is an AndroidManifest.xml where things like the App Name, and the device permissions live. Inside android/res/drawable there is an icon.png file that will set the app icon.

OSX

Inside the darwin directory, there is Contents/Resources. Inside here you can create the app icon. To do so, you need to put the icon files inside icons.iconset directory (keeping the names for the files the same), where you can put the icon. Then from inside darwin/Contents/Resources, run iconutil -c icns icons.iconset to generate the icons.icns file which will be used for the app icon. The info.plist file contains the configuration for OSX.

To do