- Extending Qt Creator Manual
- Extending Qt Creator with Lua
- Extending Qt Creator Manual 14.0.0-beta2

# Extending Qt Creator with Lua

Qt Creator can be extended with Lua scripts. The included Lua engine is based on Lua 5.4.6.

## Writing Lua Extensions

To create a new Lua extension, choose File > New Project > Library > Qt Creator Lua Plugin.

To test your new extension, start your project. Your Application Output should show Hello from Lua!.

## Lua Extension Specification

A Lua extension consists of a Lua script with the same name as the folder it is in. This is necessary for the extension to be loaded.

This script defines the specification of the extension, such as its display name, vendor, copyright.

     --- MyExtension.lua
     return {
         Name = "MyExtension",
         Version = "1.0.0",
         CompatVersion = "1.0.0",
         Vendor = "My Company",
         Category = "Tests",
         Description = "Describe what your extension does in a sentence.",
         LongDescription = [[
             Tell users more about your extension.
         ]],
         Dependencies = {
             { Name = "Core", Version = "13.0.82", Required = true },
             { Name = "Lua",  Version = "13.0.82", Required = true }
         },
         setup = function() print("Hello from Lua!") end,
         printToOutputPane = true,
     } --[[@as QtcPlugin]]

## The Setup Function

The setup function is called when the extension is loaded. This is where you can set up the functionality of your extension. Since the specification file is parsed with very limited permissions, you need to require a module where you implement the actual functionality.

     --- MyExtension.lua
     return {
         Name = "MyExtension",
         Version = "1.0.0",
         ...,
         --- This is the setup function that is called when the extension is loaded.
         --- It requires the 'init' module and calls the setup function from the returned table.
         setup = function() require 'init'.setup() end,
     }

     --- init.lua
     function setup()
         print("Hello from Lua!")
     end

     -- Returns a table with a single field 'setup' that points to the setup function.
     return {
         setup = setup
     }

## Asynchronous Operations

Some of the built-in operations work asynchronously. To handle this, use the Async module.

     local a = require 'async'
     local u = require 'Utils'

     a.sync(function()
         print("Lets wait for 5 seconds ...")
         a.wait(u.waitms(5000))
         print("... done!")
     end)

## Interactive Help

When you open a .lua file in the editor the first time, you are asked to download the Lua Language Server. This is extremely useful as it gives you context sensitive help and auto-completion.

## Qt Creator API

The Qt Creator API is available to Lua extensions via a number of modules that you can import using the `require` function. C++ extensions may provide additional modules. One example of that is the LanguageServer Extension that provides a module for creating Language Server clients.

You can find the API documentation files for the Lua modules in your Qt Creator installation. On macOS you can find them in `Qt Creator.app/Contents/Resources/lua/meta`.

Core.lua | Access and interact with the core functionality of Qt Creator.
action.lua | Create user interface actions in Qt Creator.
async.lua | Handle asynchronouse operations with the async/await Lua API.
fetch.lua | Fetch data from the internet.
gui.lua | Create user interfaces.
lsp.lua | Register Language Server clients.
messagemanager.lua | Display messages to the user.
process.lua | Run external processes.
qt.lua | Access Qt functionality.
qtc.lua | Access and extend Qt Creator.
settings.lua | Read and write settings.
simpletypes.lua | Access simple types.
utils.lua | Common utility functions and classes.

## Extending the Lua API with C++

To add functionality to the Lua Interface, you need to register a new module with the Lua Engine.

     #include <lua/luaengine.h>

     class MyCppExtension final : public ExtensionSystem::IPlugin
     {
         Q_OBJECT
         Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "MyCppExtension.json")

     public:
         MyCppExtension() {}

     private:
         void initialize() final {
             // The registered function will be called when the Lua module 'MyCppExtension' is required.
             // The returned table will be returned from the require call in Lua.
             ::Lua::LuaEngine::registerProvider("MyCppExtension", [](sol::state_view lua) -> sol::object {
                 sol::table result = lua.create_table();
                 result["myFunction"] = [](int a, int b) { return a + b; };
                 return result;
             });
          }
     };

You can then access `MyCppExtension.myFunction` from your Lua scripts like this:

     local MyCppExtension = require 'MyCppExtension'
     --- MyCppExtension is now a table with a single field 'myFunction', as it is returned from the
     --- C++ function registered via 'LuaEngine::registerProvider(...)'.
     print(MyCppExtension.myFunction(1, 2))

For more information on how to register C++ functionality, see sol2.

## Examples

### Language Server

The Qt Creator LuaLanguageClient Plugin provides support for registering your own Language Server clients. You can find an example of how to use this in the Qt Creator Extension "Lua Language Server" and "Rust Language Server".