Changed gtUi.h/c gtUiDrvr.h to cmUi.h/c cmUiDrvr.h

Makefile.am

@@ -30,8 +30,8 @@ cmSRC += src/libcm/cmMidiFilePlay.c src/libcm/cmMidiPort.c src/libcm/cmMidiFile.
 cmHDR += src/libcm/cmAudioFile.h src/libcm/cmAudioFileMgr.h src/libcm/cmMsgProtocol.h src/libcm/cmAudioSys.h src/libcm/cmAudioPortFile.h src/libcm/cmAudioFileDev.h 
 cmSRC += src/libcm/cmAudioFile.c src/libcm/cmAudioFileMgr.c src/libcm/cmMsgProtocol.c src/libcm/cmAudioSys.c src/libcm/cmAudioPortFile.c src/libcm/cmAudioFileDev.c
 
-cmHDR += src/libcm/cmDevCfg.h
-cmSRC += src/libcm/cmDevCfg.c
+cmHDR += src/libcm/cmDevCfg.h src/libcm/cmUi.h src/libcm/cmUiDrvr.h
+cmSRC += src/libcm/cmDevCfg.c src/libcm/cmUi.c
 
 cmHDR += src/libcm/cmFrameFile.h src/libcm/cmFeatFile.h src/libcm/cmCsv.h src/libcm/cmAudLabelFile.h src/libcm/cmTagFile.h
 cmSRC += src/libcm/cmFrameFile.c src/libcm/cmFeatFile.c src/libcm/cmCsv.c src/libcm/cmAudLabelFile.c src/libcm/cmTagFile.c
@@ -68,7 +68,6 @@ cmSRC += src/libcm/cmProcObj.c src/libcm/cmProc.c src/libcm/cmProc2.c src/libcm/
 cmHDR += src/libcm/app/cmOnset.h src/libcm/app/cmTimeLine.h src/libcm/app/cmScore.h src/libcm/app/cmPickup.h src/libcm/cmRbm.h
 cmSRC += src/libcm/app/cmOnset.c src/libcm/app/cmTimeLine.c src/libcm/app/cmScore.c src/libcm/app/cmPickup.c src/libcm/cmRbm.c
 
-
 if OS_LINUX
  cmSRC += src/libcm/linux/cmFileSysLinux.c  src/libcm/linux/cmAudioPortAlsa.c src/libcm/linux/cmMidiAlsa.c
  cmHDR += src/libcm/linux/cmFileSysLinux.h  src/libcm/linux/cmAudioPortAlsa.h

cmUi.h

@@ -0,0 +1,346 @@
+#ifndef cmUi_h
+#define cmUi_h
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+  /*
+    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 
+
+    TODO:
+    0) 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 to 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.7
+
+    6) 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 );
+
+  // 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 );
+
+  // 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
+  //
+
+
+  cmUiRC_t cmUiCreatePanel(   cmUiH_t uiH, unsigned newPanelId, const cmChar_t* label );
+
+  cmUiRC_t cmUiCreateBtn(         cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
+  cmUiRC_t cmUiCreateCheck(       cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, bool dflt );
+  cmUiRC_t cmUiCreateLabel(       cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
+  cmUiRC_t cmUiCreateText(        cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* text );  
+  cmUiRC_t cmUiCreateNumber(      cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* label, unsigned flags, double min, double max, double incr, double dflt );
+  cmUiRC_t cmUiCreateVSlider(     cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt );
+  cmUiRC_t cmUiCreateHMeter(      cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt ); 
+  cmUiRC_t cmUiCreateVMeter(      cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags, int    min, int    max, int    dflt ); 
+  cmUiRC_t cmUiCreateFileBtn(     cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* label, unsigned flags, const cmChar_t* dfltDir );
+  cmUiRC_t cmUiCreateMenuBtn(     cmUiH_t uiH, unsigned panelId, unsigned id, const cmChar_t* label, unsigned flags );
+  cmUiRC_t cmUiCreateMenuBtnV(    cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* lavel, unsigned flags, const cmChar_t* label0, unsigned id0, ... );
+  cmUiRC_t cmUiCreateMenuBtnJson( cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt );
+  cmUiRC_t cmUiCreateListV(       cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* label, unsigned flags, unsigned visibleRowCnt, const cmChar_t* label0, unsigned id0, ... );
+  cmUiRC_t cmUiCreateListJson(    cmUiH_t uiH, 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 panelId, unsigned id, const cmChar_t* text, unsigned eleId );
+
+  // If 'id' identifies a panel then all control belonging to the panel
+  // will also be destroyed.
+  cmUiRC_t cmUiDestroyCtl(    cmUiH_t uiH, unsigned id );
+
+  // Returns true if the control exists.
+  // For panels set id=panelId.
+  bool     cmUiCtlExists(     cmUiH_t uiH, unsigned panelId, unsigned id );
+
+  // Destroy all the controls in a panel.
+  cmUiRC_t cmUiClearPanel( cmUiH_t uiH, unsigned panelId );
+
+
+  // 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 panelId );
+  bool    cmUiSetFillRows( cmUiH_t uiH, 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 panelId );          
+  void     cmUiPlaceBelow( cmUiH_t uiH, unsigned panelId );          
+
+  // Set current base col and return previous value. Place the next
+  // control on the base row.
+  int      cmUiBaseCol(    cmUiH_t uiH, unsigned panelId, int x );   
+
+
+  // Set current base row and return previous value.
+  int      cmUiBaseRow(    cmUiH_t uiH, 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 panelId );         
+  int      cmUiH( cmUiH_t uiH, unsigned panelId );
+  void     cmUiSetWH(  cmUiH_t uiH, 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 panelId );
+  int      cmUiNextH(  cmUiH_t uiH, unsigned panelId );
+  void     cmUiSetNextWH( cmUiH_t uiH, unsigned panelId, int w, int h );
+
+  // Get/Set the default inter-control borders
+  // Set returns previous value.
+  int      cmUiHBorder( cmUiH_t uiH, unsigned panelId );
+  int      cmUiVBorder( cmUiH_t uiH, unsigned panelId );
+  int      cmUiSetHBorder( cmUiH_t uiH, unsigned panelId, int w );
+  int      cmUiSetVBorder( cmUiH_t uiH, unsigned panelId, int h );
+
+  // Get/Set the 'next' inter-control borders
+  // Set returns previous value.
+  int      cmUiNextHBorder( cmUiH_t uiH, unsigned panelId );
+  int      cmUiNextVBorder( cmUiH_t uiH, unsigned panelId );
+  int      cmUiSetNextHBorder( cmUiH_t uiH, unsigned panelId, int w );
+  int      cmUiSetNextVBorder( cmUiH_t uiH, 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 panelId, int x, int y, int w, int h );
+
+
+  //
+  // Get/set the value of UI control.  
+  //
+
+  // TODO:
+  // 1) Still need functions for setting auxilliary values like
+  //    min,max,etc..
+  // 2) A coherent model needs to be selected for determining
+  //    how local values get set.  As it is local values are
+  //    only set via callbacs from the UI driver.
+
+  // Set the value associated with a control.   
+  // These functions would be better named 'cmUiSendXXX()' since
+  // they don't actually set the local value but rather call the
+  // driver to set the UI value. The driver may then respond with
+  // a callback which will set the local value. One advantage of
+  // this is that the value will be filtered according to the
+  // ui's rules (e.g. min, max .... ) 
+  cmUiRC_t  cmUiSetInt(    cmUiH_t uiH,  unsigned id, int v );
+  cmUiRC_t  cmUiSetUInt(   cmUiH_t uiH,  unsigned id, unsigned v );
+  cmUiRC_t  cmUiSetDouble( cmUiH_t uiH,  unsigned id, double v );
+  cmUiRC_t  cmUiSetString( cmUiH_t uiH,  unsigned id, const cmChar_t* v );
+
+  // 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 id );
+  unsigned        cmUiUInt(   cmUiH_t uiH,  unsigned id );
+  double          cmUiDouble( cmUiH_t uiH,  unsigned id );
+  const cmChar_t* cmUiString( cmUiH_t uiH,  unsigned id );
+
+  // 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

cmUiDrvr.h

@@ -0,0 +1,114 @@
+#ifndef cmUiDrvr_h
+#define cmUiDrvr_h
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+  typedef unsigned cmUiRC_t;
+
+  enum
+  {
+    kOkUiRC = cmOkRC,
+    kAppNotFoundUiRC,
+    kCtlNotFoundUiRC,
+    kPanelNotFoundUiRC,
+    kPanelFullUiRC,
+    kDrvrErrUiRC,    
+    kInvalidCtlOpUiRC,
+    kInvalidColRowUiRC,
+    kInvalidIdUiRC,
+  };
+
+
+  typedef enum
+  {
+    kInvalidUiCId,
+    kPanelUiCId,
+    kBtnUiCId,
+    kCheckUiCId,
+    kMenuBtnUiCId,
+    kListUiCId,
+    kLabelUiCId,
+    kTextUiCId,
+    kNumberUiCId,
+    kSliderUiCId,
+    kProgressUiCId,
+    kMeterUiCId,
+    kFilenameUiCId,
+    kDirUiCId,
+  } cmUiCId_t;
+
+  typedef enum
+  {
+    kInvalidDId,
+    kCreateCtlDId,
+    kDestroyCtlDId,
+    kSetValDId,
+    kDestroyAllDId
+  } cmUiDId_t;
+
+  enum
+  {
+    // All controls recognize kValUiFl and kLblUiFl
+    kValUiFl   = 0x000001,
+    kLblUiFl   = 0x000002,
+
+    // Flags for Number,Progress,Meter
+    kMinUiFl   = 0x00004,
+    kMaxUiFl   = 0x00010,
+    kIncUiFl   = 0x00020,
+    kNumMask   = kValUiFl | kMinUiFl | kMaxUiFl | kIncUiFl,
+    kHorzUiFl  = 0x00040,
+    kVertUiFl  = 0x00080,
+
+    // Flags for Filename and Dir
+    kFnPatUiFl = 0x00100, // file pattern string
+    kFnDirUiFl = 0x00200, // toggle file btn type 
+    kFnMask    = kFnPatUiFl | kFnDirUiFl,
+
+    // Append list or menu element.
+    kAppendUiFl = 0x00400,
+
+    kLeftUiFl   = 0x01000,
+    kTopUiFl    = 0x02000,
+    kRightUiFl  = 0x04000,
+    kBottomUiFl = 0x08000,
+    kHCtrUiFl   = 0x10000,
+    kVCtrUiFl   = 0x20000,
+    kInsideUiFl = 0x40000,
+
+  };
+
+
+  // A control can be uniquely idenfied by 
+  // appId and usrId (appId's are unique among app's)
+  // (usrId's are unique among ctl's on an app)
+  // appId's and usrId's should be zero based low numbers
+  // because they are used internally as indexes.
+  typedef struct
+  {
+    void*       cbArg;        //
+    cmUiDId_t   dId;          // function selector id
+    unsigned    appId;        // app id (plug-in instance id)
+    unsigned    usrId;        // ctl id
+    unsigned    panelId;      // parent panel id   
+    cmUiCId_t   cId;          // UI control type 
+    unsigned    flags;        // See kXXXUiFl above.
+    int         x; 
+    int         y; 
+    int         w; 
+    int         h;
+    int         ival;
+    double      fval;
+    const char* sval;
+  } cmUiDriverArg_t;
+  
+  typedef cmUiRC_t (*cmUiDriverFunc_t)( const cmUiDriverArg_t* a );
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif