/** * @file XTPGaugeTraits.h * * @copyright * (c) 1998-2025 Codejock Software, All Rights Reserved. * * This source file is the property of Codejock Software and must not be * redistributed by any means without the explicit written permission of * Codejock Software. * * The use of this source code is governed by the terms and conditions specified * in the Toolkit Pro license agreement. Codejock Software grants you, as a * single software developer, the limited right to use this software on one * computer only. * * Contact Information: * support@codejock.com * http://www.codejock.com * */ #if !defined(__XTPGAUGETRAITS_H__) # define __XTPGAUGETRAITS_H__ # if _MSC_VER > 1000 # pragma once # endif // _MSC_VER > 1000 # include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h" class CXTPGaugeBaseType; /** * @brief * Defines a set of loaded gauge traits. */ class _XTP_EXT_CLASS CXTPGaugeTraits : public CObject { friend class CXTPGaugeBaseType; DECLARE_DYNAMIC(CXTPGaugeTraits); public: /** * @brief * Initializes an empty set of gauge traits. */ CXTPGaugeTraits(); /** * @brief * Loads a set of gauge traits from the specified source. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an evaluated * JavaScript object from strTraitsArg JSON data, then the function must return a * JavaScript object that containts the evaluated traits data. * * @param stream A stream object to read traits data from. * @param strTraitsArg Optional JSON traits to be passed to traits evaluation call if needed. */ CXTPGaugeTraits(IStream& stream, CString strTraitsArg = CString()); /** * @brief * Loads a set of gauge traits from the specified source. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an evaluated * JavaScript object from strTraitsArg JSON data, then the function must return a * JavaScript object that containts the evaluated traits data. * * @param strTraits Traits data to load. * @param strTraitsArg Optional JSON traits to be passed to traits evaluation call if needed. */ CXTPGaugeTraits(CString strTraits, CString strTraitsArg = CString()); /** * @brief * Handles traits set destruction. */ ~CXTPGaugeTraits(); /** * @brief * Gets gauge traits data. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an * evaluated JavaScript object from strTraitsArg JSON data, then the function must * return a JavaScript object that containts the evaluated traits data. * * @returns Current traits data. * @see SetTraits */ const CString& GetTraits() const; /** * @brief Sets gauge traits data. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an * evaluated JavaScript object from strTraitsArg JSON data, then the function must * return a JavaScript object that containts the evaluated traits data. * * @param strTraits Traits data to load. * @see GetTraits */ void SetTraits(CString strTraits); /** * @brief * Gets gauge traits data argument. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an * evaluated JavaScript object from strTraitsArg JSON data, then the function must * return a JavaScript object that containts the evaluated traits data. * * @returns Current traits data argument. * @see SetTraitsArgument */ const CString& GetTraitsArgument() const; /** * @brief * Sets gauge traits data argument. * * @details * Gauge traits data is either a JSON content or a JavaScript code of form (function(args) * { ... })(args). JSON traits get evaluated into a JavaScript object as is. If a * JavaScript function is provided then it gets executed with one argument that is an * evaluated JavaScript object from strTraitsArg JSON data, then the function must * return a JavaScript object that containts the evaluated traits data. * * @param strTraitsArg Traits data to load. * @see GetTraitsArgument */ void SetTraitsArgument(CString strTraitsArg); /** * @brief * Gets a custom value of a gauge trait. * * @details * Custom traits get evaluated only once upon gauge loading and provide a mechanism of * customizing existing gauge traits without need to re-create the entire traits JSON file. * So GetCustomTrait and SetCustomTrait do not access the actual * traits JSON data. Instead they operate on a separate list of custom traits to be applied upon * gauge loading. By default this list is empty. It is possible to get a custom trait value only * if it has been previously set. JSON path syntax is as simple as JavaScript object access, for * example this path: * * 
state[1].image.src
* * points to this JSON element in a JSON traits object: * * 
{
	 *   states: [
	 *     { ... },
	 *     {
	 *        image: {
	 *          src: '[path_to_svg_file]'
	 *        }
	 *     }
	 *   ]
	 * }
* * @param strJsonPath JSON path of an existing value to be accessed. * @returns Current custom trait value pointer or NULL if no value is associated * with the given path. * @see SetCustomTrait */ COleVariant* GetCustomTrait(CString strJsonPath) const; /** * @brief * Sets a custom value of a gauge trait. * * @details * Custom traits get evaluated only once upon gauge loading and provide a mechanism of * customizing existing gauge traits without need to re-create the entire traits JSON file. * So GetCustomTrait and SetCustomTrait do not access the actual * traits JSON data. Instead they operate on a separate list of custom traits to be applied upon * gauge loading. By default this list is empty. It is possible to get a custom trait value only * if it has been previously set. JSON path syntax is as simple as JavaScript object access, for * example this path: * * 
state[1].image.src
* * points to this JSON element in a JSON traits object: * * 
{
	 *   states: [
	 *     { ... },
	 *     {
	 *        image: {
	 *          src: '[path_to_svg_file]'
	 *        }
	 *     }
	 *   ]
	 * }
* * @param strJsonPath JSON path of an existing value to be accessed. * @param vtValue A new value of an JSON element defined by the JSON path provided. * @see GetCustomTrait */ void SetCustomTrait(CString strJsonPath, COleVariant vtValue); /** * @brief * Start custom traits enumeration. * * @returns The first custom trait position. * @see GetNextCustomTrait * @see GetCustomTrait * @see SetCustomTrait */ POSITION EnumCustomTraits() const; /** * @brief * Enumerates specified custom trait paths and values. * * @param pos On input it contains position of the current custom trait, on output it is * updated with the next custom trait position value, NULL indicates end of * enumeration * @param strJsonPath Upon successful completion contains a JSON path value of a custom trait * to be customized * @param pValue Upon successful completion contains a pointer to the custom trait value * @returns TRUE if enumeration can continue, FALSE if enumeration is * completed. * @see EnumCustomTraits * @see GetCustomTrait * @see SetCustomTrait */ BOOL GetNextCustomTrait(POSITION& pos, CString& strJsonPath, COleVariant*& pValue) const; /** * @brief * Gets the resource path to be used by the gauge implementation to load images and other * assets from. Setting a new value will also invalidate the traits argument value. * * @returns Current resource path value. * @see GetResourceModule * @see SetResourceModule */ const CString& GetResourcePath() const; /** * @brief Sets the resource path to be used by the gauge implementation to load images and * other assets from. Setting a new value will also invalidate the traits argument value. * * @param strPath Path value. Empty path value will make traits argument an empty string. * @see GetResourceModule * @see SetResourceModule */ void SetResourcePath(CString strPath); //----------------------------------------------------------------------- // Summary: // Gets/sets resource module handle and resource namespace to be used by the gauge // implementation to load images and other assets from. Setting a new value will also // invalidate the traits argument value. // Parameters: // hResMod - Resource module handle. NULL handle value will make traits argument an empty // string. // pNamespace - An optional string to be added as a resource name prefix for all requested // gauge resources. The string must contain only alpha-numeric a hyphen and a underscore // symbols. // Returns: // Current resource handle module and resource namespace. // See also: // GetResourcePath, SetResourcePath //----------------------------------------------------------------------- /** * @brief Gets resource module handle to be used by the gauge implementation to load images * and other assets from. Setting a new value will also invalidate the traits argument value. * * @returns Current resource handle module. * @see GetResourceNamespace * @see SetResourceModule * @see GetResourcePath * @see SetResourcePath */ HMODULE GetResourceModule() const; /** * @brief Gets resource module handle to be used by the gauge implementation to load images * and other assets from. Setting a new value will also invalidate the traits argument value. * * @returns Current resource handle module. * @see GetResourceModule * @see SetResourceModule * @see GetResourcePath * @see SetResourcePath */ const CString& GetResourceNamespace() const; /** * @brief Sets resource module handle to be used by the gauge implementation to load images * and other assets from. Setting a new value will also invalidate the traits argument value. * * @param hResMod Resource module handle. NULL handle value will make traits * argument an empty string. * @param pNamespace An optional string to be added as a resource name prefix for all requested * gauge resources. The string must contain only alpha-numeric a hyphen and a underscore * symbols. * @see GetResourceModule * @see GetResourceNamespace * @see GetResourcePath * @see SetResourcePath */ BOOL SetResourceModule(HMODULE hResMod, LPCTSTR pNamespace = NULL); private: CString GetCompositeTraitsArgument() const; private: CString m_strTraits; CString m_strTraitsArg; CString m_strResPathTraits; CMapStringToPtr m_customTraits; CString m_strResPath; CString m_strResNamespace; HMODULE m_hResMod; }; AFX_INLINE CXTPGaugeTraits::CXTPGaugeTraits() { } AFX_INLINE CXTPGaugeTraits::CXTPGaugeTraits(CString strTraits, CString strTraitsArg /*= CString()*/) : m_strTraits(strTraits) , m_strTraitsArg(strTraitsArg) , m_hResMod(NULL) { } AFX_INLINE void CXTPGaugeTraits::SetTraits(CString strTraits) { m_strTraits = strTraits; } AFX_INLINE const CString& CXTPGaugeTraits::GetTraits() const { return m_strTraits; } AFX_INLINE void CXTPGaugeTraits::SetTraitsArgument(CString strTraitsArg) { m_strTraitsArg = strTraitsArg; } AFX_INLINE const CString& CXTPGaugeTraits::GetTraitsArgument() const { return m_strTraitsArg; } AFX_INLINE POSITION CXTPGaugeTraits::EnumCustomTraits() const { return m_customTraits.GetStartPosition(); } AFX_INLINE const CString& CXTPGaugeTraits::GetResourcePath() const { return m_strResPath; } AFX_INLINE HMODULE CXTPGaugeTraits::GetResourceModule() const { return m_hResMod; } AFX_INLINE const CString& CXTPGaugeTraits::GetResourceNamespace() const { return m_strResNamespace; } # include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h" #endif // !defined(__XTPGAUGETRAITS_H__)