-#ifndef __DALI_TOOLKIT_STYLE_MANAGER_H__
-#define __DALI_TOOLKIT_STYLE_MANAGER_H__
+#ifndef DALI_TOOLKIT_STYLE_MANAGER_H
+#define DALI_TOOLKIT_STYLE_MANAGER_H
/*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2020 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*/
// EXTERNAL INCLUDES
-#include <dali/public-api/adaptor-framework/orientation.h>
#include <dali/public-api/adaptor-framework/style-change.h>
// INTERNAL INCLUDES
namespace Dali
{
-
namespace Toolkit
{
-
namespace Internal DALI_INTERNAL
{
class StyleManager;
}
/**
- * @brief StyleManager provides the following functionalities:
+ * @addtogroup dali_toolkit_managers
+ * @{
+ */
+
+/**
+ * @brief StyleManager informs applications of system theme change,
+ * and supports application theme change at runtime.
*
* Applies various styles to Controls using the properties system.
- * On theme change a signal is raised that controls can be configured to listen to.
*
- * The default theme is automatically loaded and applied.
+ * On theme change, it automatically updates all controls, then raises
+ * a signal to inform the application.
+ *
+ * The default theme is automatically loaded and applied, followed by
+ * any application specific theme defined in Application::New().
*
- * If the application wants to customize the theme, RequestThemeChange needs to be called.
- * Also, the default orientation is Portrait, if the application wants to adapt to the orientation change, call SetOrientation or SetOrienationValue.
- * @code
- * const char* CUSTOM_THEME = DALI_SCRIPT_DIR "tizen-dark-theme.json";
+ * If the application wants to customize the theme, RequestThemeChange
+ * needs to be called.
*
- * void OnInit(Application& app)
- * {
- * Toolkit::StyleManager::Get().RequestThemeChange( CUSTOM_THEME );
- * Toolkit::StyleManager::Get().SetOrientation( app.GetWindow().GetOrientation() );
- * ...
- * }
- * @endcode
+ * To supply resource paths ( in json ) the following constant is available: APPLICATION_RESOURCE_PATH.
+ * It provides the path to the application resource root folder, from there the filename can an be specified along with
+ * any sub folders, e.g Images, Models etc.
+ * The APPLICATION_RESOURCE_PATH can be retrieved using Application::GetResourcePath()
*
- * Internal::Control can be configured to register for the signals that are required from StyleManager,
- * such as theme change.
+ * Signals
+ * | %Signal Name | Method |
+ * |------------------------------------------------------------|
+ * | styleChanged | @ref StyleChangedSignal() |
+ * @SINCE_1_1.32
*/
-class DALI_IMPORT_API StyleManager : public BaseHandle
+class DALI_TOOLKIT_API StyleManager : public BaseHandle
{
public:
-
- // Signals
- typedef Signal< void ( StyleManager, StyleChange ) > StyleChangeSignalType;
+ /// @brief Style Changed signal. Emitted after controls have been updated.
+ typedef Signal<void(StyleManager, StyleChange::Type)> StyleChangedSignalType;
/**
- * @brief Create a StyleManager handle; this can be initialised with StyleManager::Get()
- * Calling member functions with an uninitialised handle is not allowed.
+ * @brief Creates a StyleManager handle; this can be initialized with StyleManager::Get().
+ *
+ * Calling member functions with an uninitialized handle is not allowed.
+ * @SINCE_1_1.32
*/
StyleManager();
/**
- * @brief Destructor
+ * @brief Destructor.
*
* This is non-virtual since derived Handle types must not contain data or virtual methods.
+ * @SINCE_1_1.32
*/
~StyleManager();
/**
- * @brief Get the singleton of StyleManager object.
+ * @brief Gets the singleton of StyleManager object.
*
- * @return A handle to the StyleManager control.
+ * @SINCE_1_1.32
+ * @return A handle to the StyleManager control
*/
static StyleManager Get();
/**
- * @brief Specify the orientation value directly for the style manager
+ * @brief Applies a new theme to the application. This will be merged
+ * on top of the default Toolkit theme.
*
- * @param[in] orientation The orientation in degrees
- */
- void SetOrientationValue( int orientation );
-
- /**
- * @brief Return the orientation value
+ * If the application theme file doesn't style all controls that the
+ * application uses, then the default Toolkit theme will be used
+ * instead for those controls.
*
- * @return The orientation value
- */
- int GetOrientationValue();
-
- /**
- * @brief Set the orientation object. This will take precedence over setting the orientation value.
+ * On application startup, it is suggested that the theme file name is
+ * passed to Application::New instead of using this API to prevent
+ * controls being styled more than once.
+ * @sa Application::New().
*
- * @param[in] orientation Device orientation
+ * @SINCE_1_1.32
+ * @param[in] themeFile If a relative path is specified, then this is relative
+ * to the directory returned by Application::GetResourcePath()
*/
- void SetOrientation( Orientation orientation );
+ void ApplyTheme(const std::string& themeFile);
/**
- * @brief Return the orientation object
+ * @brief Applies the default Toolkit theme.
*
- * @return The orientation.
- */
- Orientation GetOrientation();
-
- /**
- * @brief Make a request to set the theme JSON file to one that exists in the Toolkit package.
+ * Request that any application specific styling is removed
+ * and that the default Toolkit theme is re-applied.
*
- * Multiple requests per event processing cycle can be made, but only the final one will be acted
- * on in the event processing finished callback.
- *
- * @param[in] themeFile This is just the JSON theme file name and not the full path.
+ * @SINCE_1_1.32
*/
- void RequestThemeChange( const std::string& themeFile );
+ void ApplyDefaultTheme();
/**
- * @brief Request a change to the default theme
- */
- void RequestDefaultTheme();
-
- /**
- * @brief Set a constant for use when building styles
+ * @brief Sets a constant for use when building styles.
*
- * A constant is used in JSON files e.g. "my-image":"{ROOT_PATH}/mypath/image.jpg"
- * where the string "{ROOT_PATH}" is substituted with the value.
+ * A constant is used in JSON files e.g. "myImage":"{RELATIVE_PATH}/image.jpg"
+ * where the string "{RELATIVE_PATH}" is substituted with the value.
*
+ * @SINCE_1_1.32
* @param[in] key The key of the constant
* @param[in] value The value of the constant
*/
- void SetStyleConstant( const std::string& key, const Property::Value& value );
+ void SetStyleConstant(const std::string& key, const Property::Value& value);
/**
- * @brief Return the style constant set for a specific key
+ * @brief Returns the style constant set for a specific key.
*
+ * @SINCE_1_1.32
* @param[in] key The key of the constant
* @param[out] valueOut The value of the constant if it exists
*
- * @return If the constant for key exists then return the constant in valueOut and return true
+ * @return If the constant for key exists, then return the constant in valueOut and return true
*/
- bool GetStyleConstant( const std::string& key, Property::Value& valueOut );
+ bool GetStyleConstant(const std::string& key, Property::Value& valueOut);
/**
- * @brief Apply the specified style to the control.
- *
- * The JSON file will be cached and subsequent calls using the same JSON file name will
- * use the already loaded cached values instead.
+ * @brief Applies the specified style to the control.
*
- * @param[in] control The control to apply style.
- * @param[in] jsonFileName The name of the JSON style file to apply.
- * @param[in] styleName The name of the style within the JSON file to apply.
+ * @SINCE_1_1.32
+ * @param[in] control The control to which to apply the style
+ * @param[in] jsonFileName The name of the JSON style file to apply. If a
+ * relative path is specified, then this is relative to the directory
+ * returned by Application::GetResourcePath()
+ * @param[in] styleName The name of the style within the JSON file to apply
*/
- void ApplyStyle( Toolkit::Control control, const std::string& jsonFileName, const std::string& styleName );
+ void ApplyStyle(Toolkit::Control control, const std::string& jsonFileName, const std::string& styleName);
public: // Signals
-
/**
- * @brief This signal is emitted whenever the style (e.g. theme/font change) is changed on device
+ * @brief This signal is emitted after the style (e.g. theme/font change) has changed
+ * and the controls have been informed.
+ *
+ * @SINCE_1_1.32
* A callback of the following type may be connected:
* @code
* void YourCallbackName( StyleManager styleManager, StyleChange change );
* @endcode
- * @return The signal to connect to.
+ * @return The signal to connect to
*/
- StyleChangeSignalType& StyleChangeSignal();
+ StyleChangedSignalType& StyleChangedSignal();
public:
-
+ /// @cond internal
/**
- * @brief Creates a new handle from the implementation.
+ * @brief Allows the creation of a StyleManager handle from an internal pointer.
*
- * @param[in] impl A pointer to the object.
+ * @note Not intended for application developers
+ * @SINCE_1_1.32
+ * @param[in] impl A pointer to the object
*/
- explicit DALI_INTERNAL StyleManager( Internal::StyleManager *impl );
+ explicit DALI_INTERNAL StyleManager(Internal::StyleManager* impl);
+ /// @endcond
}; // class StyleManager
+/**
+ * @}
+ */
+
} // namespace Toolkit
} // namespace Dali
-
-#endif /* __DALI_TOOLKIT_STYLE_MANAGER_H__ */
+#endif // DALI_TOOLKIT_STYLE_MANAGER_H
projects / platform / core / uifw / dali-toolkit.git / blobdiff