317 lines
17 KiB
C++
317 lines
17 KiB
C++
//| Copyright: (C) 2020-2024 Kevin Larke <contact AT larke DOT org>
|
|
//| License: GNU GPL version 3.0 or above. See the accompanying LICENSE file.
|
|
#ifndef cwUI_H
|
|
#define cwUI_H
|
|
|
|
#include "cwUiDecls.h"
|
|
|
|
namespace cw
|
|
{
|
|
namespace ui
|
|
{
|
|
typedef handle<struct ui_str> handle_t;
|
|
|
|
|
|
// Callback for application notification.
|
|
// (e.g. the GUI changed the value of a UI element)
|
|
typedef rc_t (*uiCallback_t)( void* cbArg, unsigned wsSessId, opId_t opId, unsigned parentAppId, unsigned uuId, unsigned appId, unsigned chanId, const value_t* value );
|
|
|
|
// Callback with messages for the GUI as JSON strings
|
|
// { "op":"create", "type":<>, "appId":<>, "parentUuId":<>, "name":<> (type specific fields) }
|
|
// { "op":""value", "uuid":<> "value":<> }
|
|
typedef rc_t (*sendCallback_t)( void* cbArg, unsigned wsSessId, const void* msg, unsigned msgByteN );
|
|
|
|
rc_t create(
|
|
handle_t& h,
|
|
sendCallback_t sendCbFunc,
|
|
void* sendCbArg,
|
|
uiCallback_t uiCbFunc,
|
|
void* uiCbArg,
|
|
const object_t* uiRsrc = nullptr,
|
|
const appIdMap_t* appIdMapA = nullptr,
|
|
unsigned appIdMapN = 0,
|
|
unsigned fmtBufByteN = 4096 );
|
|
|
|
rc_t destroy( handle_t& h );
|
|
|
|
rc_t enableCache( handle_t h, unsigned cacheByteCnt=4096 );
|
|
rc_t flushCache( handle_t h );
|
|
|
|
unsigned sessionIdCount(handle_t h); // Count of connected remote UI's
|
|
const unsigned* sessionIdArray(handle_t h); // Array of 'sessionIdCount()' remote UI id's
|
|
|
|
// A new remote UI was connected
|
|
rc_t onConnect( handle_t h, unsigned wsSessId );
|
|
|
|
// A UI was disconnected
|
|
rc_t onDisconnect( handle_t h, unsigned wsSessId );
|
|
|
|
// Receive a msg from a remote UI.
|
|
//
|
|
// Note that individual messages are delinated with zero termination.
|
|
// Therefore a message which is not zero terminated is considered
|
|
// a partial message and will be buffered until the suffix of the message
|
|
// arrives.
|
|
rc_t onReceive( handle_t h, unsigned wsSessId, const void* msg, unsigned byteN );
|
|
|
|
// Locate an element whose parent uuid is 'parentUuId' with a child named 'eleName'.
|
|
unsigned parentAndNameToAppId( handle_t h, unsigned parentAppId, const char* eleName );
|
|
unsigned parentAndNameToUuId( handle_t h, unsigned parentAppId, const char* eleName );
|
|
unsigned parentAndAppIdToUuId( handle_t h, unsigned parentAppId, unsigned appId );
|
|
|
|
const char* findElementName( handle_t h, unsigned uuId );
|
|
unsigned findElementAppId( handle_t h, unsigned uuId );
|
|
|
|
// Return the uuid of the first matching 'eleName' or 'appId'.
|
|
unsigned findElementUuId( handle_t h, const char* eleName, unsigned chanId = kInvalidId );
|
|
unsigned findElementUuId( handle_t h, unsigned appId, unsigned chanId = kInvalidId );
|
|
unsigned findElementUuId( handle_t h, unsigned parentUuId, const char* eleName, unsigned chanId = kInvalidId );
|
|
unsigned findElementUuId( handle_t h, unsigned parentUuId, unsigned appId, unsigned chanId = kInvalidId );
|
|
|
|
|
|
// Create multiple UI elements from an object_t representation.
|
|
// The channel id of all elements created from the object will be assigned 'chanId'.
|
|
// The 'label' string identifies a child wihtin the outer object (e.g. o,fn,text, create( ... uiRsrc, ...)) which should be used to create the element.
|
|
rc_t createFromObject( handle_t h, const object_t* o, unsigned parentUuId=kInvalidId, unsigned chanId=kInvalidId, const char* label=nullptr);
|
|
rc_t createFromFile( handle_t h, const char* fn, unsigned parentUuId=kInvalidId, unsigned chanId=kInvalidId);
|
|
rc_t createFromText( handle_t h, const char* text, unsigned parentUuId=kInvalidId, unsigned chanId=kInvalidId);
|
|
// This function uses 'label' to locate the child of the internal uiRsrc (passed to 'create()') as the element configuration resource.
|
|
rc_t createFromRsrc( handle_t h, const char* label, unsigned parentUuId=kInvalidId, unsigned chanId=kInvalidId);
|
|
|
|
//
|
|
// Create Sincgle UI elements on the UI instance identified by wsSessId.
|
|
//
|
|
// uuIdRef: Returns the automatically generated id for this element.
|
|
// It is unique across all elements associated with this ui::handle.
|
|
// Note that this id is NOT generated per wsSession, it is only generated
|
|
// the first time a particular element of this ui::handle is created.
|
|
//
|
|
// wsSessId: Identifies a particular instance (websock session) of the UI.
|
|
// Multiple instances of a UI may exist for a single application instance each will have a unique wsSessId.
|
|
// Set this value to kInvalidId to create this element on all existing websock sessions. Note that this is
|
|
// an unusual use since UI elements are usually created when new sessions are connected and therefore
|
|
// a specific wsSessId is available.
|
|
//
|
|
// parentUuId: uuid of parent element that the new element will be a child of.
|
|
//
|
|
// eleName: (optional) HTML ele id of the new element.
|
|
//
|
|
// appId: (optional) Application id. This is the application variable which this UI element represents.
|
|
// This id is generally the same across all UI instances.
|
|
//
|
|
// clas: (optional) HTML class of the new element
|
|
//
|
|
// title: (optional) Visible Text label associated with this element.
|
|
//
|
|
|
|
rc_t createDiv( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createLabel( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createButton( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
|
|
// Create check: w/o value. The value will be read from the engine via the UI 'echo' event.
|
|
rc_t createCheck( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
|
|
// Create check: w/ value. The value will be sent to the engine as the new value of the associated varaible.
|
|
rc_t createCheck( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, bool value );
|
|
|
|
rc_t createSelect( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createOption( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createStrDisplay( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createStrDisplay( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, const char* value );
|
|
rc_t createStr( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createStr( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, const char* value );
|
|
rc_t createNumbDisplay(handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, unsigned decPl );
|
|
rc_t createNumbDisplay(handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, unsigned decPl, double value );
|
|
rc_t createNumb( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, double minValue, double maxValue, double stepValue, unsigned decPl );
|
|
rc_t createNumb( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, double minValue, double maxValue, double stepValue, unsigned decPl, double value );
|
|
rc_t createProg( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, double minValue, double maxValue );
|
|
rc_t createProg( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title, double minValue, double maxValue, double value );
|
|
rc_t createLog( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createVList( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
rc_t createHList( handle_t h, unsigned& uuIdRef, unsigned parentUuId, const char* eleName, unsigned appId, unsigned chanId, const char* clas, const char* title );
|
|
|
|
rc_t setTitle( handle_t h, unsigned uuId, const char* title );
|
|
|
|
rc_t setNumbRange( handle_t h, unsigned uuId, double minValue, double maxValue, double stepValue, unsigned decPl, double value );
|
|
rc_t setProgRange( handle_t h, unsigned uuId, double minValue, double maxValue, double value );
|
|
rc_t setLogLine( handle_t h, unsigned uuId, const char* text );
|
|
rc_t emptyParent( handle_t h, unsigned uuId );
|
|
|
|
rc_t setClickable( handle_t h, unsigned uuId, bool clickableFl=true );
|
|
rc_t clearClickable( handle_t h, unsigned uuId );
|
|
bool isClickable( handle_t h, unsigned uuId );
|
|
|
|
rc_t setSelect( handle_t h, unsigned uuId, bool enableFl=true );
|
|
rc_t clearSelect( handle_t h, unsigned uuId );
|
|
bool isSelected( handle_t h, unsigned uuId );
|
|
|
|
rc_t setVisible( handle_t h, unsigned uuId, bool enableFl=true );
|
|
rc_t clearVisible( handle_t h, unsigned uuId );
|
|
bool isVisible( handle_t h, unsigned uuId );
|
|
|
|
rc_t setEnable( handle_t h, unsigned uuId, bool enableFl=true );
|
|
rc_t clearEnable( handle_t h, unsigned uuId );
|
|
bool isEnabled( handle_t h, unsigned uuId );
|
|
|
|
rc_t setOrderKey( handle_t h, unsigned uuId, int orderKey );
|
|
int getOrderKey( handle_t h, unsigned uuId );
|
|
|
|
// Scroll the element identified by 'uuId' to the top of the list.
|
|
// (uuId must identify a list element whose parent is a 'uiList')
|
|
rc_t setScrollTop( handle_t h, unsigned uuId );
|
|
|
|
// setBlob() allocates internal memeory and copies the contents of blob[blobByeN]
|
|
rc_t setBlob( handle_t h, unsigned uuId, const void* blob, unsigned blobByteN );
|
|
const void* getBlob( handle_t h, unsigned uuId, unsigned& blobByteN_Ref );
|
|
rc_t clearBlob( handle_t h, unsigned uuId );
|
|
|
|
// Register parent/child/name app id's
|
|
rc_t registerAppIdMap( handle_t h, const appIdMap_t* map, unsigned mapN );
|
|
|
|
unsigned elementChildCount( handle_t h, unsigned uuId );
|
|
rc_t elementChildUuId( handle_t h, unsigned uuId, unsigned* bufA, unsigned bufN, unsigned& actualN );
|
|
|
|
unsigned elementPhysChildCount( handle_t h, unsigned uuId );
|
|
rc_t elementPhysChildUuId( handle_t h, unsigned uuId, unsigned* bufA, unsigned bufN, unsigned& actualN );
|
|
|
|
|
|
// Release an element an all of it's children.
|
|
rc_t destroyElement( handle_t h, unsigned uuId );
|
|
|
|
// Send a value from the application to the UI via a JSON messages.
|
|
// Set wsSessId to kInvalidId to send to all sessions.
|
|
rc_t sendValueBool( handle_t h, unsigned uuId, bool value );
|
|
rc_t sendValueInt( handle_t h, unsigned uuId, int value );
|
|
rc_t sendValueUInt( handle_t h, unsigned uuId, unsigned value );
|
|
rc_t sendValueFloat( handle_t h, unsigned uuId, float value );
|
|
rc_t sendValueDouble( handle_t h, unsigned uuId, double value );
|
|
rc_t sendValueString( handle_t h, unsigned uuId, const char* value );
|
|
|
|
rc_t sendMsg( handle_t h, const char* msg );
|
|
|
|
void report( handle_t h );
|
|
void realTimeReport( handle_t h );
|
|
|
|
|
|
namespace ws
|
|
{
|
|
typedef handle<struct ui_ws_str> handle_t;
|
|
|
|
typedef struct args_str
|
|
{
|
|
const char* physRootDir;
|
|
const char* dfltPageFn;
|
|
object_t* uiRsrc;
|
|
unsigned port;
|
|
unsigned rcvBufByteN;
|
|
unsigned xmtBufByteN;
|
|
unsigned fmtBufByteN;
|
|
unsigned idleMsgPeriodMs; // min period without messages before an idle message is generated
|
|
unsigned queueBlkCnt;
|
|
unsigned queueBlkByteCnt;
|
|
bool extraLogsFl; // Report the websock LLL_NOTICE logs
|
|
} args_t;
|
|
|
|
rc_t parseArgs( const object_t& o, args_t& args, const char* object_label="ui" );
|
|
rc_t releaseArgs( args_t& args );
|
|
|
|
rc_t create( handle_t& h,
|
|
const args_t& args,
|
|
void* cbArg,
|
|
uiCallback_t uiCbFunc,
|
|
const object_t* uiRsrc = nullptr,
|
|
const appIdMap_t* appIdMapA = nullptr,
|
|
unsigned appIdMapN = 0,
|
|
websock::cbFunc_t wsCbFunc = nullptr );
|
|
|
|
rc_t create( handle_t& h,
|
|
unsigned port,
|
|
const char* physRootDir,
|
|
void* cbArg,
|
|
uiCallback_t uiCbFunc,
|
|
const object_t* uiRsrc = nullptr,
|
|
const appIdMap_t* appIdMapA = nullptr,
|
|
unsigned appIdMapN = 0,
|
|
websock::cbFunc_t wsCbFunc = nullptr,
|
|
const char* dfltPageFn = "index.html",
|
|
unsigned idleMsgPeriodMs = 50,
|
|
unsigned rcvBufByteN = 1024,
|
|
unsigned xmtBufByteN = 1024,
|
|
unsigned fmtBufByteN = 4096,
|
|
unsigned queueBlkCnt = 4,
|
|
unsigned queueBlkByteCnt = 4096,
|
|
bool extraLogsFl = false );
|
|
|
|
rc_t destroy( handle_t& h );
|
|
|
|
// This function should be called periodically to send and receive
|
|
// queued messages to and from the websocket.
|
|
// Note that this call may block for up to 'wsTimeOutMs' milliseconds
|
|
// while waiting for incoming websocket messages.
|
|
rc_t exec( handle_t h, unsigned wsTimeOutMs );
|
|
|
|
// This function executes the internal default websock callback function.
|
|
// It is useful if the user provides a custom websock callback function
|
|
// and wants to fallback to the default websock->ui interaction.
|
|
rc_t onReceive( handle_t h, unsigned protocolId, unsigned sessionId, websock::msgTypeId_t msg_type, const void* msg, unsigned byteN );
|
|
|
|
websock::handle_t websockHandle( handle_t h );
|
|
ui::handle_t uiHandle( handle_t h );
|
|
void realTimeReport( handle_t h );
|
|
|
|
}
|
|
|
|
namespace srv
|
|
{
|
|
|
|
typedef handle<struct ui_ws_srv_str> handle_t;
|
|
|
|
rc_t create( handle_t& h,
|
|
const ws::args_t& args,
|
|
void* cbArg,
|
|
uiCallback_t uiCbFunc,
|
|
const appIdMap_t* appIdMapA = nullptr,
|
|
unsigned appIdMapN = 0,
|
|
unsigned wsTimeOutMs = 50,
|
|
websock::cbFunc_t wsCbFunc = nullptr );
|
|
|
|
rc_t create( handle_t& h,
|
|
unsigned port,
|
|
const char* physRootDir,
|
|
void* cbArg,
|
|
uiCallback_t uiCbFunc,
|
|
const object_t* uiRsrc = nullptr,
|
|
const appIdMap_t* appIdMapA = nullptr,
|
|
unsigned appIdMapN = 0,
|
|
unsigned wsTimeOutMs = 50,
|
|
websock::cbFunc_t wsCbFunc = nullptr,
|
|
const char* dfltPageFn = "index.html",
|
|
unsigned idleMsgPeriodMs = 50,
|
|
unsigned rcvBufByteN = 1024,
|
|
unsigned xmtBufByteN = 1024,
|
|
unsigned fmtBufByteN = 4096,
|
|
unsigned queueBlkCnt = 4,
|
|
unsigned queueBlkByteCnt = 4096,
|
|
bool extraLogsFl = false );
|
|
|
|
|
|
rc_t destroy( handle_t& h );
|
|
|
|
rc_t start( handle_t h );
|
|
rc_t stop( handle_t h );
|
|
|
|
thread::handle_t threadHandle( handle_t h );
|
|
websock::handle_t websockHandle( handle_t h );
|
|
ui::handle_t uiHandle( handle_t h );
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
#endif
|