X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fbuilder%2Fbuilder.h;h=a9750146cb2c187e2e913f523aceeab9c50021f9;hb=9cbb34fdf7a5cdec7a7bf2feba20f948d6c0e6a3;hp=8df26191117bc5eac6464721e3eb7a16adface60;hpb=e2eda444afbe82e9591fe198eef339227f90a616;p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git diff --git a/dali-toolkit/public-api/builder/builder.h b/dali-toolkit/public-api/builder/builder.h index 8df2619..a975014 100644 --- a/dali-toolkit/public-api/builder/builder.h +++ b/dali-toolkit/public-api/builder/builder.h @@ -1,26 +1,30 @@ #ifndef __DALI_TOOLKIT_UIBUILDER_H__ #define __DALI_TOOLKIT_UIBUILDER_H__ -// -// Copyright (c) 2014 Samsung Electronics Co., Ltd. -// -// Licensed under the Flora License, Version 1.0 (the License); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://floralicense.org/license/ -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an AS IS BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -// INTERNAL INCLUDES -#include - -namespace Dali DALI_IMPORT_API +/* + * Copyright (c) 2015 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +// EXTERNAL INCLUDES +#include +#include +#include +#include + +namespace Dali { namespace Toolkit @@ -32,15 +36,14 @@ class Builder; } /** - * Builder - * This class provides the ability to load an actor tree from a string representation. + * This class provides the ability to load and style an actor tree from a string representation. * - * The following example is hello world in JSON. + * The following is an example in JSON. * * @code * * { - * "styles": + * "templates": // are named instantiable actor trees * { * "default-text": * { @@ -50,6 +53,24 @@ class Builder; * "scale": [50,50,1] * } * }, + * "styles": // are named property sets applied to actor trees + * { + * "my-style": + * { + * "size": [10,10,1] // root properties applied to a given root actor + * "actors": // properties applied to actors found by name from root + * { + * "ok": // properties for an actor named "ok" + * { + * "scale":[5,5,1], + * }, + * "cancel": + * { + * "scale":[50,50,1], + * } + * }, + * }, + * }, * "stage": * [ * { @@ -60,29 +81,43 @@ class Builder; * ] * } * - * - * * @endcode * - * The following is how to load the json data. - * + * The following shows a method to load the json file. * @code - * * Builder builder = Builder::New(); - * * std::string json_data(ReadFile("layout.json")); - * * builder.LoadFromString(json_data); - * - * // 1) load all actors in the "stage" section to the root layer + * @endcode + * Examples + * - Load all actors in the "stage" section to the root layer + * @code * builder.AddActors( Stage::GetCurrent().GetRootLayer() ); + * @endcode + * + * - Create an actor tree from the "templates" section + * @code + * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) ); + * @endcode + * + * - Style an actor tree from the "styles" section + * @code + * builder.ApplyStyle( "my-style", actor ); + * @endcode * - * // or 2) create an actor from the library "styles" section - * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) ); + * - Create an actor tree from json + * @code + * TextActor actor = TextActor::DownCast( builder.CreateFromJson("{\"type\":\"TextActor\",\"font\":\"\",\"scale\":[50,50,1]}") ); + * @endcode * + * - Apply a style to an actor tree from json + * @code + * builder.ApplyFromJson( textActor, ("{\"scale\":[5,5,1]}") ); * @endcode + * */ - class Builder : public BaseHandle + +class DALI_IMPORT_API Builder : public BaseHandle { public: /** @@ -98,9 +133,11 @@ class Builder; static Builder New(); /** - * Virtual destructor. + * @brief Destructor + * + * This is non-virtual since derived Handle types must not contain data or virtual methods. */ - virtual ~Builder(); + ~Builder(); /** * UI string data format @@ -122,6 +159,63 @@ class Builder; void LoadFromString( const std::string& data, UIFormat format = JSON ); /** + * @brief Adds user defined constants to all future style template or animation expansions + * + * e.g. + * Property::Map map; + * map["IMAGE_DIRECTORY"] = "/usr/share/images"; + * builder.AddConstants( map ); + * + * @pre The Builder has been initialized. + * @param map The user defined constants used in template expansions. + */ + void AddConstants( const Property::Map& map ); + + /** + * @brief Adds or modifies a user defined constant to all future style template or animation expansions + * + * e.g. + * @code + * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" ); + * @endcode + * + * @pre The Builder has been initialized. + * @param key The constant name to add or update + * @param value The new value for the constant. + */ + void AddConstant( const std::string& key, const Property::Value& value ); + + /** + * @brief Gets all currently defined constants. + * + * e.g. + * @code + * Property::Map map = builder.GetConstants(); // get copy of current constants + * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification + * builder.AddConstants( map ); // write back changes + * @endcode + * + * @pre The Builder has been initialized. + * @return A reference to the currently defined constants. + */ + const Property::Map& GetConstants() const; + + /** + * @brief Gets a currently defined constant, or returns Property::INVALID + * + * e.g. + * @code + * Property::Map map = builder.GetConstants(); // get copy of current constants + * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification + * builder.AddConstants( map ); // write back changes + * @endcode + * + * @pre The Builder has been initialized. + * @param key The constant name to search for. + */ + const Property::Value& GetConstant( const std::string& key ) const; + + /** * Creates an animation from the set of known animations * e.g. * Animation a = builder.CreateAnimation( "wobble"); @@ -135,96 +229,150 @@ class Builder; Animation CreateAnimation( const std::string& animationName ); /** - * Creates an object (e.g. an actor) from the set of known styles + * @brief Creates an animation from the set of known animations with user defined constants + * * e.g. - * mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) ); + * Property::Map map; + * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template + * Animation a = builder.CreateAnimation( "wobble"); * * @pre The Builder has been initialized. * @pre Preconditions have been met for creating dali objects ie Images, Actors etc - * @pre The styleName has been loaded from the styles section of the data representation - * and contains 'type' property used to create the object. - * @param styleName The set of styles/properties to set on the handle object. + * @pre The animationName exists in the animations section of the data representation + * @pre The map contains all the constant expansions in the style template + * @param animationName The animation name to create + * @param map The user defined constants used in style template expansion. * @returns The base handle of the created object */ - BaseHandle CreateFromStyle( const std::string& styleName ); + Animation CreateAnimation( const std::string& animationName, const Property::Map& map ); /** - * Apply a style (a collection of properties) to an actor. + * @brief Creates an animation from the set of known animations. + * + * The animation is applied to a specific actor. + * e.g. + * Actor myInstance = builder.Create( "template-actor-tree" ) + * Animation a = builder.CreateAnimation( "wobble", myInstance ); + * * @pre The Builder has been initialized. * @pre Preconditions have been met for creating dali objects ie Images, Actors etc - * @param styleName The name of the set of style properties to set on the handle object. - * @param handle Then handle of the object on which to set the properties. + * @pre The animationName exists in the animations section of the data representation + * @param animationName The animation name to create + * @param sourceActor The starting point in an actor tree, from which to look for property owners + * @returns The base handle of the created object */ - void ApplyStyle( const std::string& styleName, Handle& handle ); + Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor ); /** - * Add the actor tree in the "stage" section to the actor toActor. - * ie if the representation has a 'stage' section that contains a tree of - * actors then - * builder.AddActors( Stage::GetCurrent().GetRootLayer() ); - * will create and add the actors to the stage root layer. - * @param toActor The actor to add the created actors to + * @brief Creates an animation from the set of known animations with user defined constants + * + * The animation is applied to a specific actor. + * e.g. + * Property::Map map; + * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template + * Actor myInstance = builder.Create( "template-actor-tree" ) + * Animation a = builder.CreateAnimation( "wobble", myInstance); + * + * @pre The Builder has been initialized. + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @pre The animationName exists in the animations section of the data representation + * @pre The map contains all the constant expansions in the style template + * @param animationName The animation name to create + * @param map The user defined constants used in style template expansion. + * @param sourceActor The starting point in an actor tree, from which to look for property owners + * @returns The base handle of the created object */ - void AddActors( Actor toActor ); + Animation CreateAnimation( const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor ); /** - * Adds actors in the sectionName to the actor toActor. - * ie if the representation has a sectionName section that contains a tree of - * actors then - * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() ); - * will create and add the actors to the stage root layer. - * @param sectionName The section name to search for the actor tree - * @param toActor The actor to add the created actors to + * @brief Creates an object (e.g. an actor) from the set of known style templates + * + * e.g. + * mActor.Add( Actor::DownCast(builder.Create( "default-text")) ); + * + * @pre The Builder has been initialized. + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @pre The templateName exists in the templates section of the data representation + * and contains 'type' property used to create the object. + * @param templateName The template to apply in creation. + * @returns The base handle of the created object */ - void AddActors( const std::string §ionName, Actor toActor ); + BaseHandle Create( const std::string& templateName ); /** - * @deprecated Font as a separate asset is no longer supported - * Get's a Font asset previously created at load time - * An empty handle is returned otherwise. + * @brief Creates an object from the style templates with user defined constants + * + * e.g. + * Property::Map map; + * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template + * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) ); + * * @pre The Builder has been initialized. - * @param name The name given to a Font in the loaded representation - * @return A handle to a Font if found, otherwise empty. + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @pre The templateName exists in the templates section of the data representation + * and contains 'type' property used to create the object. + * @param templateName The template used to create the object. + * @param map The user defined constants used in template expansion. + * @returns The base handle of the created object */ - Font GetFont( const std::string &name ) const; + BaseHandle Create( const std::string& templateName, const Property::Map& map ); /** - * Get's a TextStyle asset previously created at load time + * @brief Creates an object (e.g. an actor) from given json snippet + * + * e.g. + * Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}")); + * * @pre The Builder has been initialized. - * @param name The name given to a TextStyle in the loaded representation - * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @param json The json snippet used to create the object. + * @returns The base handle of the created object if any */ - TextStyle GetTextStyle( const std::string &name ) const; + BaseHandle CreateFromJson( const std::string& json ); /** - * @deprecated Images as a separate asset is no longer supported - * Get's an Image asset previously created at load time - * An empty handle is returned otherwise. + * Apply a style (a collection of properties) to an actor. * @pre The Builder has been initialized. - * @param name The name given to an Image in the loaded representation - * @return A handle to an Image if found, otherwise empty + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @param styleName The name of the set of style properties to set on the handle object. + * @param handle Then handle of the object on which to set the properties. + * + * @return Return true if the style was found */ - Image GetImage( const std::string &name ) const; + bool ApplyStyle( const std::string& styleName, Handle& handle ); /** - * @deprecated Actors no longer held by builder - * Get's an Actor previously created at load time - * An empty handle is returned otherwise. + * Apply a style (a collection of properties) to an actor from the given json snippet * @pre The Builder has been initialized. - * @param name The name given to an Actor in the loaded representation - * @return A handle to an Actor if found, otherwise empty + * @pre Preconditions have been met for creating dali objects ie Images, Actors etc + * @param handle Then handle of the object on which to set the properties. + * @param json The json snippet used to create the object. + * + * @return Return true if the json snippet was parsed */ - Actor GetActor( const std::string &name ) const; + bool ApplyFromJson( Handle& handle, const std::string& json ); + /** - * @deprecated Animations no longer held by builder - * Get's an Animation previously created at load time - * An empty handle is returned otherwise. - * @pre The Builder has been initialized. - * @param name The name given to an Animation in the loaded representation - * @return A handle to an Animation if found, otherwise empty + * Add the actor tree in the "stage" section to the actor toActor. + * ie if the representation has a 'stage' section that contains a tree of + * actors then + * builder.AddActors( Stage::GetCurrent().GetRootLayer() ); + * will create and add the actors to the stage root layer. + * @param toActor The actor to add the created actors to */ - Animation GetAnimation( const std::string &name ) const; + void AddActors( Actor toActor ); + + /** + * Adds actors in the sectionName to the actor toActor. + * ie if the representation has a sectionName section that contains a tree of + * actors then + * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() ); + * will create and add the actors to the stage root layer. + * @param sectionName The section name to search for the actor tree + * @param toActor The actor to add the created actors to + */ + void AddActors( const std::string §ionName, Actor toActor ); /** * Create a render task set. @@ -252,14 +400,28 @@ class Builder; FrameBufferImage GetFrameBufferImage( const std::string &name ); /** - * @deprecated. Builder no longer holds actor handles/references - * Provides a list of the top level actors previously created at load time - * @return A container of Actors found at the top level of the loaded representation + * Get or create Path from the Path instance library. + * An empty handle is returned otherwise. + * @pre The Builder has been initialized. + * @param name The name of a Path in the loaded representation + * @return A handle to a Path if found, otherwise empty + */ + Path GetPath( const std::string &name ); + + // Signals + + /** + * @brief Builder signal type + */ + typedef Signal< void () > BuilderSignalType; + + /** + * @brief Signal emitted when a quit action is requested by the builder. */ - ActorContainer GetTopLevelActors( void ) const; + BuilderSignalType& QuitSignal(); private: - Builder(Internal::Builder *impl); + explicit DALI_INTERNAL Builder(Internal::Builder *impl); }; // class Builder