Zuble QML Types   |  Zuble C++ Classes   |  Table of Contents

ZControlModule QML Type

Base type for Zuble's MVC control modules. Extend this object to implement a Zuble application control module. More...

Import Statement: import controller .




Detailed Description

A Zuble control module consists of a command dispatcher and its associated command handler functions. Each control module contains a message queue that allows commands to be processed asynchronously. Control modules will typically use ZScriptThread objects to perform I/O operations in order to avoid blocking the UI thread.

Extend ZControlModule to create a new control module type. Command handlers for the new type are defined by adding functions to the extended type with the same names as the command action code that they will process. Each function will be passed all command objects having the same action code as the function name.

Example: var cmd = {actionCode: "doSomething", myParam: "whatever"}

function doSomething(cmd){console.log("Doing " + cmd.myParam)}

prints: "Doing whatever"

Alternately a control module can implement its own command dispatch mechanism instead of using the automatic dispatch feature. Set autoDispatch = false and ZControlModule will issue the dispatchCommand signal instead of calling command handler functions.

Control modules can have multiple clients. Each Control Module client receives a ZMailslot object to communicate with the control module. The module listens to all mailslots and processes requests asynchronously. Clients send command messages to the mailslot and receive responses when command execution is completed.

Commands are dispatched by a central dispatcher routine and handled by the dispatchCommand signal handler. Handler functions control the flow of command execution by maintaining a local state machine within the command object itself that gets updated for each asynchronous step in the command's algorithm. When the last step has been processed a response is sent to the command's originating mailslot.

WARNING - the following property names of the client payload are reserved for use by this object to dispatch commands and responses: zSlotName, zErrorMsg

Property Documentation

autoDispatch : bool

Controls how actions are dispatched

When autoDispatch == true command handler functions are called automatically. The dispatchCommand signal is not sent.

When autoDispatch == false the dispatchCommand signal is sent. Control module functions are not called.

controlModuleReady : bool

When control module initialization has completed set this property to true and emit the controllerReady signal.

errorCode : int

No idea what this is for

errorMessage : string

No idea what this is for

Signal Documentation

controllerReady(string = moduleName)

Extended types should both set controlModuleReady = true and emit this signal once their internal initialization has completed.

moduleName can be used to filter controllerReady signals.

dispatchCommand(var = cmd)

allows extended objects to implement custom command dispatching.

Set autoDispatch = false to enable this signal and implement custom dispatch handling.

cmd is the command object to dispatch.

Method Documentation

ZMailslot newClient(string clientName)

Creates a ZMailslot object for the new client and returns it.

clientName is the name of the control module client. This name is used to route command responses back to the client mailslot and must be unique.

Client communicates with control module by sending command messages and receiving responses on the returned ZMailslot object.

Command messages have the following format:

{actionCode: "<actionCodeName>",...}

where <actionCodeName> is the name of the control module function that will be called to process the command, and ... represents user-defined properties. (zSlotName and zErrorMsg properties are RESERVED. DO NOT USE!)

Returns a ZMailslot object