Merge "ImageView ResourceReady logic update" into devel/master
[platform/core/uifw/dali-toolkit.git] / docs / content / shared-javascript-and-cpp-documentation / fundamentals.md
1 <!--
2 /**-->
3
4 # DALi Fundamentals  {#fundamentals}
5
6 ## Actors and the Stage {#actors-and-stage}
7
8 Actor is the primary object with which DALi applications interact.
9 A DALi application uses a hierarchy of Dali::Actor objects to position visible content.
10 An actor inherits a position relative to its parent, and can be moved relative to this point.
11 UI controls can be built by combining multiple actors.
12
13 The Stage is a top-level object used for displaying a tree of Actors.
14 To display the contents of an actor, it must be added to the Dali::Stage,
15
16 The following example shows how to connect a new actor to the stage:
17
18 ~~~{.cpp}
19 Actor actor = Actor::New();
20 Stage::GetCurrent().Add(actor);
21 ~~~
22
23 ~~~{.js}
24 var actor = new dali.Actor();
25 dali.stage.add( actor );
26 ~~~
27
28 ## The Coordinate System {#coordinate-system}
29
30 The Stage has a 2D size, which matches the size of the application window.
31 The default **unit 1 is 1 pixel with default camera and** the default coordinate system in DALi has the **origin at the top-left corner, with positive X to right, and position Y going
32 downwards**.  This is intended to be convenient when laying-out 2D views.
33
34 ![ ](../assets/img/coordinate-system-and-stage.png)
35 ![ ](coordinate-system-and-stage.png)
36
37
38 ## Positioning Actors {#positioning-actors}
39
40 An actor inherits its parent's position.  The relative position between the actor & parent is determined by 3 properties:
41
42 1) ParentOrigin.  This Vector3 property defines a point within the parent actor's area.
43
44 ![ ](../assets/img/parent-origin.png)
45 ![ ](parent-origin.png)
46
47 The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D DALi world.  The actor's position is relative to this point.
48
49 2) AnchorPoint.  This Vector3 property defines a point within the child actor's area.
50
51 ![ ](../assets/img/anchor-point.png)
52 ![ ](anchor-point.png)
53
54 The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D DALi world.  The actor's position is also relative to this point.
55
56 3) Position.  This is the position vector between the parent-origin and anchor-point.
57
58 ![ ](../assets/img/actor-position.png)
59 ![ ](actor-position.png)
60
61 The default is (X = 0, Y = 0), so an actor placed directly without modifying the parent origin, anchor point or position would appear centred around the top left corner of its parent.
62
63 An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5), would appear in the center of the screen.  Likewise an actor with position (X = actorWidth*0.5, Y = actorWidth*0.5), would appear at the top-left of the screen. However, basic positioning like that is normally done via changing the parent origin and/or anchor point instead - use ParentOrigin::CENTER and AnchorPoint::CENTER to place the actor in the center of the screen, and ParentOrigin::TOP_LEFT and AnchorPoint::TOP_LEFT to place it inside the screen on the top left.
64
65 Note that since DALi is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
66
67 ## Scene Graph {#scene-graph}
68
69 From Wikipedia...
70   
71 A scene graph is a collection of nodes in a graph or tree structure.
72 A node may have many children but often only a single parent,
73 with the effect of a parent applied to all its child nodes;
74 an operation performed on a group automatically propagates
75 its effect to all of its members. In many programs, associating
76 a geometrical transformation matrix (see also transformation and matrix)
77 at each group level and concatenating such matrices together is an
78 efficient and natural way to process such operations. A common feature,
79 for instance, is the ability to group related shapes/objects into a
80 compound object that can then be moved, transformed, selected,
81 etc. as easily as a single object.
82
83 ### How does this relate to the DALi public API?
84
85 Actors are effectively nodes that receive input (touch events) and act as a
86 container for draw-able elements (which are also nodes) and other actors.
87
88 @class _Guide_DALi_Fundamentals
89
90 */