X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=base%2Fdali-toolkit%2Fpublic-api%2Fbuilder%2Fbuilder.h;h=98d3d8c8213f7e8b916f31cbfb2cc4855187faad;hp=723b6754fd30232e112a096421a0caab17e27bd2;hb=87b3b1f9a40c85ab6120d77bc6c0d356ae45faf3;hpb=022b76df6f53c2860f2684ef1ffee81af1805e2e diff --git a/base/dali-toolkit/public-api/builder/builder.h b/base/dali-toolkit/public-api/builder/builder.h index 723b675..98d3d8c 100644 --- a/base/dali-toolkit/public-api/builder/builder.h +++ b/base/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) 2014 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 @@ -31,18 +35,15 @@ namespace Internal DALI_INTERNAL class Builder; } -typedef std::map PropertyValueMap; - /** - * 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": * { @@ -52,6 +53,24 @@ typedef std::map PropertyValueMap; * "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": * [ * { @@ -62,29 +81,43 @@ typedef std::map PropertyValueMap; * ] * } * - * - * * @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 * - * // or 2) create an actor from the library "templates" section + * - 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 * + * - 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: /** @@ -100,9 +133,11 @@ typedef std::map PropertyValueMap; 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 @@ -127,14 +162,14 @@ typedef std::map PropertyValueMap; * @brief Adds user defined constants to all future style template or animation expansions * * e.g. - * PropertyValueMap map; + * 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 PropertyValueMap& map ); + void AddConstants( const Property::Map& map ); /** * @brief Adds or modifies a user defined constant to all future style template or animation expansions @@ -155,7 +190,7 @@ typedef std::map PropertyValueMap; * * e.g. * @code - * PropertyValueMap map = builder.GetConstants(); // get copy of current constants + * 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 @@ -163,14 +198,14 @@ typedef std::map PropertyValueMap; * @pre The Builder has been initialized. * @return A reference to the currently defined constants. */ - const PropertyValueMap& GetConstants() const; + const Property::Map& GetConstants() const; /** * @brief Gets a currently defined constant, or returns Property::INVALID * * e.g. * @code - * PropertyValueMap map = builder.GetConstants(); // get copy of current constants + * 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 @@ -197,7 +232,7 @@ typedef std::map PropertyValueMap; * @brief Creates an animation from the set of known animations with user defined constants * * e.g. - * PropertyValueMap map; + * Property::Map map; * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template * Animation a = builder.CreateAnimation( "wobble"); * @@ -209,7 +244,7 @@ typedef std::map PropertyValueMap; * @param map The user defined constants used in style template expansion. * @returns The base handle of the created object */ - Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map ); + Animation CreateAnimation( const std::string& animationName, const Property::Map& map ); /** * @brief Creates an animation from the set of known animations. @@ -233,7 +268,7 @@ typedef std::map PropertyValueMap; * * The animation is applied to a specific actor. * e.g. - * PropertyValueMap map; + * 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); @@ -247,17 +282,7 @@ typedef std::map PropertyValueMap; * @param sourceActor The starting point in an actor tree, from which to look for property owners * @returns The base handle of the created object */ - Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor ); - - /** - * @deprecated Use Create() - */ - BaseHandle CreateFromStyle( const std::string& styleName ); - - /** - * @deprecated Use Create() - */ - BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map ); + Animation CreateAnimation( const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor ); /** * @brief Creates an object (e.g. an actor) from the set of known style templates @@ -278,7 +303,7 @@ typedef std::map PropertyValueMap; * @brief Creates an object from the style templates with user defined constants * * e.g. - * PropertyValueMap map; + * Property::Map map; * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) ); * @@ -290,7 +315,20 @@ typedef std::map PropertyValueMap; * @param map The user defined constants used in template expansion. * @returns The base handle of the created object */ - BaseHandle Create( const std::string& templateName, const PropertyValueMap& map ); + BaseHandle Create( const std::string& templateName, const Property::Map& map ); + + /** + * @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. + * @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 + */ + BaseHandle CreateFromJson( const std::string& json ); /** * Apply a style (a collection of properties) to an actor. @@ -304,6 +342,18 @@ typedef std::map PropertyValueMap; bool ApplyStyle( const std::string& styleName, Handle& handle ); /** + * Apply a style (a collection of properties) to an actor from the given json snippet + * @pre The Builder has been initialized. + * @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 + */ + bool ApplyFromJson( Handle& handle, const std::string& json ); + + + /** * 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 @@ -325,54 +375,6 @@ typedef std::map PropertyValueMap; void AddActors( const std::string §ionName, Actor toActor ); /** - * @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. - * @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. - */ - Font GetFont( const std::string &name ) const; - - /** - * Get's a TextStyle asset previously created at load time - * @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 - */ - TextStyle GetTextStyle( const std::string &name ) const; - - /** - * @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. - * @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 - */ - Image GetImage( const std::string &name ) const; - - /** - * @deprecated Actors no longer held by builder - * Get's an Actor previously created at load time - * An empty handle is returned otherwise. - * @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 - */ - Actor GetActor( const std::string &name ) const; - - /** - * @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 - */ - Animation GetAnimation( const std::string &name ) const; - - /** * Create a render task set. * @pre The Builder has been initialized. * @param name The library name of the render task set. @@ -398,14 +400,28 @@ typedef std::map PropertyValueMap; 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 SignalV2< void () > Signal; + + /** + * @brief Signal emitted when a quit action is requested by the builder. */ - ActorContainer GetTopLevelActors( void ) const; + Signal& QuitSignal(); private: - Builder(Internal::Builder *impl); + explicit DALI_INTERNAL Builder(Internal::Builder *impl); }; // class Builder