libcm/src/cmUi.h

//| Copyright: (C) 2009-2020 Kevin Larke <contact AT larke DOT org> 
//| License: GNU GPL version 3.0 or above. See the accompanying LICENSE file.
#ifndef cmUi_h
#define cmUi_h

#ifdef __cplusplus
extern "C" {
#endif
  /*( { file_desc:"UI control manager for rtSys." kw:[rtSys]}

    cmUI implements a platform independent UI control manager 
    for multiple simultaneous applications. In this context
    an 'application' can be seen as a plug-in style program.

    The goal of the manager is to support the easy construction 
    of panels of graphic user interface controls.

    
     
    Operation:

    1) A cmUi manager is allocated by the master program. See cmUiAlloc(). 

    2) The master program then assigns a 'driver' to implmenent
    the commands issued by cmUi.  All commands can be 
    described using the cmUiDriverArg_t record.

    3) The master program then registers client applications with
    the cmUi manager by calling cmUiCreateApp().  

    4) Prior to calling any of the client application functions
    the master or client app. must call cmUiSetAppId(). This
    function sets the current application id and thereby slightly
    simplifies the client app interface by not requiring the
    app id be passed with every client app. function call.

    5) Once the current app. id is set with cmUiSetAppId() 
    the client app can make multiple calls to the cmUi manager
    to create or query controls.

    6) Calls to create controls result in callbacks to the 
    driver function which manages the actual windowing and
    initial event handling.

    7) Events generated by the driver based graphic controls 
    are routed back to the cmUi manager through calls to
    cmUiOnDriverEvent().

    8) The cmUiOnDriverEvent() internally caches the 
    state/value of the control based on the event information
    and calls the 'cbFunc' function registered with the
    cmUi manager by cmUiAlloc(). This call is intended to
    notify the client applications of changes in the state/value
    of a user interface control.
    
    Notes:
    1) Application id's must be unique among all applications.
    Control id's must be unique among all controls assigned
    to the same application. Both application and control id's
    are used internally as array indexes they should therefore
    be the low, positive, and densely packed integers.

    2) All communication between the cmUi and the driver,
    and all callbacks from the cmUi to the master app. 
    use the cmUiDriverArg_t structure 

    3) The panel tabs act like radio buttons.  When a tab is
    selected the clicked tab generates one event for each
    tab (cId=kPanelUiCId usrId=panelId) w/ ival=1 for the 
    selected tab and ival=0 for all other tabs.

    TODO:
    0) [DONE] Remove the 'cbArg' from the cmUiDriverArg_t record and 
    pass it as a separate paramenter in the cmUiDriverFunc_t calls.

    1) The controls should be based on a multilevel tree model
    not the simple two layer panel->controls framework used now.
    
    2) Given that access to the control values can be non-blocked
    and fast many controls won't need to report changes back to
    the client - the client can simply read the control value
    as necessary directly from the cmUi manager.  To decrease
    event processing overhead controls should therefore be 
    flagged as 'callback/no-callback'.  Some controls like
    buttons should default to turning the flag on, while other
    controls, like numbers, should default to turning it off.

    3) Implement support for the creation of arrays of controls.
    This can be implemented with a scheme similar to 'next rect'.
    cmUiSetupArray(uiH,panelId,baseCtlId,cnt).  
    
    4) Come up with a threading model. For example maybe 
    control creation should use a blocking scheme since it is
    generally too time consuming to do during real-time operation
    anyway.  If the control flow generated from driver event
    callbacks then allows value, but not structural changes,
    then non blocking will be necessary.

    5) The cmUiDriverArg_t structure is used for both
    commands to the driver and callbacks from the driver.
    Many of the fields are not use for event callbacks.
    Which fields are used under which circumstances should
    be documented. This would allow decreasing the size
    of the record during serialization.

    6) [DONE] Write a serialization/deserialization routines for cmUiDriverArg_t.
    unsigned cmUiDriverArgSerialBufByteCount(const cmUiDriverArg_t* a);
    cmUiRC_t cmUiDriverArgSerialize( const cmUiDriverArg_t* a, char* buf, bufByteCnt );
    cmUiRC_t cmUiDriverArgDeserialize( cmUiDriverArg_t* a, const char* buf, bufByteCnt );

    7) There is no duplex model for validating and then displaying the
    value of a control.

  */
  //)
  
  //(
  typedef cmHandle_t cmUiH_t;


  extern cmUiH_t cmUiNullHandle;

  //=============================================================================================
  //
  // Master program API
  //

  // Allocate the cmUi manager. If the driver function is not
  // yet available then set drvrFunc to NULL and use 
  // cmUiSetDriver() to set the driver function at a later
  // time.  cmUiAlloc() stores but does not call the driver
  // and so it is not needed when the cmUI manager is 
  // constructed - however it must be set prior to making
  // any other calls to the manager.
  cmUiRC_t cmUiAlloc( 
    cmCtx_t*         ctx, 
    cmUiH_t*         hp, 
    cmUiDriverFunc_t drvrFunc, // UI driver function 
    void*            drvrArg,
    cmUiDriverFunc_t cbFunc,   // client event callback function
    void*            cbArg );

  // Release all apps but assume that the driver has already
  // been released.
  cmUiRC_t cmUiFree(  cmUiH_t* hp );

  // Validate the cmUiH_t handle.
  bool     cmUiIsValid( cmUiH_t h );

  // Set the driver function. This function allows the driver
  // set in cmUiAlloc() to be replaced or set following the
  // call to cmUiAlloc().
  //
  // By setting the driver function to
  // NULL the application can prevent callback to the driver.
  // This is useful if the driver has been release prior
  // to the UI manager begining destroyed.
  void cmUiSetDriver( cmUiH_t h, cmUiDriverFunc_t drvrFunc, void* drvrArg );

  // Register a client application with the cmUi manager.
  // 'appId' must not have been used by any other previously registered.
  // application.
  // Automatically sets and restores the ambient appId.
  // In a plug-in context this function is generally called 
  // just prior a instantiating a plug-in object.
  cmUiRC_t cmUiCreateApp(  cmUiH_t uiH, unsigned appId, unsigned asSubIdx );

  // Return true if 'appId' is active.
  bool     cmUiAppIsActive( cmUiH_t uiH, unsigned appId );


  // Notify the cmUi manager that the resources associated
  // with a client application can be released.
  // Automatically sets and restores the ambient appId.
  cmUiRC_t cmUiDestroyApp( cmUiH_t uiH, unsigned appId );

  // Release all apps.
  // Automatically sets and restores the ambient appId.
  cmUiRC_t cmUiDestroyAllApps( cmUiH_t h );


  // The master program sets the ambient 'appId' prior to passing control
  // to a client which will make User API calls.  By making the
  // 'appId' an ambient parameter the User API calls are slightly
  // simplified because they do not have to include it in each of the
  // function calls.
  //cmUiRC_t cmUiSetAppId( cmUiH_t uiH, unsigned appId );
  //unsigned cmUiAppId(    cmUiH_t uiH );

  unsigned cmUiAppIdToAsSubIndex( cmUiH_t uiH, unsigned appId );

  // Return the count of app's.
  unsigned cmUiAppCount( cmUiH_t uiH );


  // Callbacks from the driver arrive via this function.
  cmUiRC_t cmUiOnDriverEvent( cmUiH_t uiH, const cmUiDriverArg_t* p );


  //=============================================================================================
  // 
  // Client Application API
  //

  // See above note on panel tabs acting like radio buttons.
  cmUiRC_t cmUiCreatePanel(   cmUiH_t uiH, unsigned appId, unsigned newPanelId, const cmChar_t* label, unsigned flags );

  cmUiRC_t cmUiCreateBtn(         cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
  cmUiRC_t cmUiCreateCheck(       cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, bool dflt );
  cmUiRC_t cmUiCreateLabel(       cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
  cmUiRC_t cmUiCreateString(      cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* text );  
  cmUiRC_t cmUiCreateConsole(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* text );
  cmUiRC_t cmUiCreateNumber(      cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, double min, double max, double incr, double dflt );
  cmUiRC_t cmUiCreateHSlider(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, double min, double max, double incr, double dflt );
  cmUiRC_t cmUiCreateVSlider(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, double min, double max, double incr, double dflt );
  cmUiRC_t cmUiCreateProgress(    cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt );
  cmUiRC_t cmUiCreateHMeter(      cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt ); 
  cmUiRC_t cmUiCreateVMeter(      cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt ); 
  cmUiRC_t cmUiCreateFileBtn(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* dfltDir, const cmChar_t* patStr );
  cmUiRC_t cmUiCreateDirBtn(      cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* dfltDir );
  cmUiRC_t cmUiCreateMenuBtn(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
  cmUiRC_t cmUiCreateMenuBtnV(    cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* lavel, unsigned flags, const cmChar_t* label0, unsigned id0, va_list vl );
  cmUiRC_t cmUiCreateMenuBtnA(    cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* lavel, unsigned flags, const cmChar_t* label0, unsigned id0, ... );
  cmUiRC_t cmUiCreateMenuBtnJson( cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* lavel, unsigned flags, const cmJsonNode_t* root, const cmChar_t* memberLabel );
  cmUiRC_t cmUiCreateList(        cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt );
  cmUiRC_t cmUiCreateListV(       cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt, const cmChar_t* label0, unsigned id0, va_list vl );
  cmUiRC_t cmUiCreateListA(       cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt, const cmChar_t* label0, unsigned id0, ... );
  cmUiRC_t cmUiCreateListJson(    cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt, const cmJsonNode_t* root, const cmChar_t* memberLabel );

  // If 'id' identifies a 'list' control use tabs as column separators.
  cmUiRC_t cmUiAppendListEle(    cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, const cmChar_t* text, unsigned eleId );

  // Remove all the elements of a list control.
  cmUiRC_t cmUiClearList(        cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id );

  // Enable/Disable a control
  cmUiRC_t cmUiEnableCtl( cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id, bool enableFl );
  
  // Enable/disable all controls on a panel except those included in the var args list.
  // Terminate the var args list with cmInvalidId.
  cmUiRC_t cmUiEnableAllExceptV( cmUiH_t uiH, unsigned appId, unsigned panelId, bool enableFl, va_list vl );
  cmUiRC_t cmUiEnableAllExcept( cmUiH_t uiH, unsigned appId, unsigned panelId, bool enableFl, ... );

  // If 'id' identifies a panel then all control belonging to the panel
  // will also be destroyed.
  cmUiRC_t cmUiDestroyCtl(    cmUiH_t uiH, unsigned appId, unsigned id );

  // Returns true if the control exists.
  // For panels set id=panelId.
  //bool     cmUiCtlExists(     cmUiH_t uiH, unsigned appId, unsigned panelId, unsigned id );

  // Destroy all the controls in a panel.
  cmUiRC_t cmUiClearPanel( cmUiH_t uiH, unsigned appId, unsigned panelId );

  cmUiRC_t cmUiSelectPanel( cmUiH_t uiH, const cmChar_t* label );

  //------------------------------------------------------------------------------------------
  // Location: 

  // 1) If a 'next rect' is set the control will be placed according to it.
  // 2) If cmUiSetBaseCol() was set then the control will be placed at the
  //    base col and base row.
  // 3) If cmUiPlaceRight() or cmUIPlaceBelow() have been called since the
  //    previous control was created then the new control will be placed
  //    accordingly.
  // 4) The control will be placed according to the 'fill rows' flag. 
  //    If not set (default) the new control  will be placed in the 
  //    base column below the previous control.  
  //    If 'fill rows' is set the new control will be placed on the 
  //    same row to the right of the previous control.
  //    If there is no previous control then it will be placed
  //    in the base column and base row.

  // Get/Set the fill directions. If the 'fill columns' flag is enabled
  // then the next control is placed below the previous control otherwise
  // the next control is placed to the right of the next control.
  bool    cmUiFillRows( cmUiH_t uiH, unsigned appId, unsigned panelId );
  bool    cmUiSetFillRows( cmUiH_t uiH, unsigned appId, unsigned panelId, bool enableFl );

  
  // Place the next control to the right/below of the previous ctl.
  // These flags override the current fill row/col setting.
  // Note that 'place right' and 'place below' are mutually
  // exclusive. Enabling one disables the other.
  void     cmUiPlaceRight( cmUiH_t uiH, unsigned appId, unsigned panelId );          
  void     cmUiPlaceBelow( cmUiH_t uiH, unsigned appId, unsigned panelId );

  // Place the next control at the base column below the previous ctl.
  void     cmUiNewLine(    cmUiH_t uiH, unsigned appId, unsigned panelId );

  // Set/Get current base col and return previous value. Place the next
  // control on the base row.
  int      cmUiBaseCol(       cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiSetBaseCol(    cmUiH_t uiH, unsigned appId, unsigned panelId, int x );   


  // Set/Get current base row and return previous value.
  int      cmUiBaseRow(       cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiSetBaseRow(    cmUiH_t uiH, unsigned appId, unsigned panelId, int y );   

  // Size:
  // 1) If a 'next rect' is set the control will be placed according
  //    to it.
  // 2) If a 'next w/h' is set the control will be placed according
  //    to it. The 'next w/h' setting is only active for the 
  //    next control created.
  // 3) The w/h of the new control will be set to the default w/h.
  //

  // Get/Set the default control width and height.
  // Set returns previous value.
  int      cmUiW(      cmUiH_t uiH, unsigned appId, unsigned panelId );         
  int      cmUiH(      cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiSetW(   cmUiH_t uiH, unsigned appId, unsigned panelId, int w );
  int      cmUiSetH(   cmUiH_t uiH, unsigned appId, unsigned panelId, int h );
  void     cmUiSetWH(  cmUiH_t uiH, unsigned appId, unsigned panelId, int w, int h );

  // Get/Set the control width and height for only the next control.
  // Set returns previous value.
  int      cmUiNextW(     cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiNextH(     cmUiH_t uiH, unsigned appId, unsigned panelId );
  void     cmUiSetNextW(  cmUiH_t uiH, unsigned appId, unsigned panelId, int w );
  void     cmUiSetNextH(  cmUiH_t uiH, unsigned appId, unsigned panelId, int h );
  void     cmUiSetNextWH( cmUiH_t uiH, unsigned appId, unsigned panelId, int w, int h );

  // Get/Set the default inter-control borders
  // Set returns previous value.
  int      cmUiHBorder( cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiVBorder( cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiSetHBorder( cmUiH_t uiH, unsigned appId, unsigned panelId, int w );
  int      cmUiSetVBorder( cmUiH_t uiH, unsigned appId, unsigned panelId, int h );

  // Get/Set the 'next' inter-control borders
  // Set returns previous value.
  int      cmUiNextHBorder( cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiNextVBorder( cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiSetNextHBorder( cmUiH_t uiH, unsigned appId, unsigned panelId, int w );
  int      cmUiSetNextVBorder( cmUiH_t uiH, unsigned appId, unsigned panelId, int h );

  // Place the next control at the following coordinates. The 
  // specified coordinates are only active during the next
  // cmUiCreateXXX() call. Setting the 'next rect' overrides all
  // other layout directives.
  cmUiRC_t cmUiNextRect( cmUiH_t uiH, unsigned appId, unsigned panelId, int x, int y, int w, int h );
  
  // Get the location/size of the previously created control.
  // All ref. args are optional.
  cmUiRC_t cmUiPrevRect( cmUiH_t uiH, unsigned appId, unsigned panelId, int* xRef, int* yRef, int* wRef, int* hRef );
  int      cmUiPrevL(    cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiPrevT(    cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiPrevR(    cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiPrevB(    cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiPrevW(    cmUiH_t uiH, unsigned appId, unsigned panelId );
  int      cmUiPrevH(    cmUiH_t uiH, unsigned appId, unsigned panelId );

  //------------------------------------------------------------------------------------------
  //
  // Get/set the value of UI control.  
  //

  // TODO:
  // +  Need functions for setting auxilliary values like
  //    min,max,etc..

  // Set the value associated with a control.   
  // Set the local value of the specified control and then 
  // send the value to the UI driver so that the UI reflects this value.
  cmUiRC_t  cmUiSetInt(    cmUiH_t uiH,  unsigned appId, unsigned id, int v );
  cmUiRC_t  cmUiSetUInt(   cmUiH_t uiH,  unsigned appId, unsigned id, unsigned v );
  cmUiRC_t  cmUiSetDouble( cmUiH_t uiH,  unsigned appId, unsigned id, double v );
  cmUiRC_t  cmUiSetString( cmUiH_t uiH,  unsigned appId, unsigned id, const cmChar_t* v );
  cmUiRC_t  cmUiSetVPrintf(cmUiH_t uiH,  unsigned appId, unsigned id, const cmChar_t* fmt, va_list vl );
  cmUiRC_t  cmUiSetPrintf( cmUiH_t uiH,  unsigned appId, unsigned id, const cmChar_t* fmt, ... );

  // Get the value associated with a control. These functions return
  // the control value cached in the local control, they do not need 
  // to call the driver and are therefore very fast.
  int             cmUiInt(    cmUiH_t uiH, unsigned appId,  unsigned id );
  unsigned        cmUiUInt(   cmUiH_t uiH, unsigned appId,  unsigned id );
  double          cmUiDouble( cmUiH_t uiH, unsigned appId,  unsigned id );
  const cmChar_t* cmUiString( cmUiH_t uiH, unsigned appId,  unsigned id );

  unsigned        cmUiListEleCount( cmUiH_t uiH, unsigned appId, unsigned id );
  unsigned        cmUiListEleId(    cmUiH_t uiH, unsigned appId, unsigned id, unsigned index );
  const cmChar_t* cmUiListEleLabel( cmUiH_t uiH, unsigned appId, unsigned id, unsigned index );
  unsigned        cmUiListEleLabelToIndex( cmUiH_t uiH, unsigned appId, unsigned id, const cmChar_t* label );

  // Query/set the current error state.
  cmUiRC_t   cmUiLastRC( cmUiH_t uiH );
  cmUiRC_t   cmUiSetRC( cmUiH_t uiH, cmUiRC_t rc );

  //)
  
#ifdef __cplusplus
}
#endif

#endif