遊戲人生 人生遊戲

Working with Display Objects and the Stage

Creating Display Objects

You don't actually create these objects directly. Instead, you create special kinds of DisplayObjects such as rectangles, circles, images, text, groups, etc.

創建顯示對象
你實際上並不直接創建這些對象。相反，你建立專門種的DisplayObject如矩形，圓形，圖像，文字，團體等

These objects are all first-class citizens. You can change their position, rotate them, animate them, turn them into buttons, etc.

這些對象都是一等公民。你可以改變它們的位置，旋轉，動畫他們，把他們融入按鈕等

All of these objects share common properties and methods that are described in the Display Objectschapter of Corona SDK Language and API Reference.

All instances of DisplayObject can be treated like normal Lua tables. This means you can add your own properties to the object as long as they don't conflict with the names of DisplayObject’s predefined properties and method. The one exception is that you cannot index into a DisplayObject as an array using numerical indices.

所有這些對象共享共同的屬性和方法所描述的顯示 Objectschapter電暈 SDK的語言和API參考。

所有的DisplayObject實例可以像對待普通的Lua表。這意味著你可以添加自己的屬性的對象，只要他們不衝突的名字DisplayObject的預定義的屬性和方法。唯一的例外是，你不能索引到一個 DisplayObject作為數組的數值指標。

Painter’s Model 畫家的模型

DisplayObjects are drawn to the screen using the Painter's Model of drawing. The easiest way to think of this is to imagine an actual painting. Here, the paint you apply at the beginning is below the paint you apply later. Each successive brush stroke obscures the strokes that came before.

的DisplayObject繪製到屏幕上使用Painter的模型圖。最簡單的方法認為這是想像一個真正的繪畫。在這裡，您申請的油漆在開始低於你申請後的油漆。每個連續的筆觸來掩蓋筆劃過。

You can think of a DisplayObject as analogous to a brush stroke. When you create a DisplayObject, you are “painting” a new object over existing display objects. As you draw more objects to the screen, the objects you draw last will obscure the ones you drew before.

你能想到的一個 DisplayObject作為類似於筆觸。當您創建一個 DisplayObject，你是“畫“一個新的目的，即在現有的顯示對象。當你吸引更多的對象到屏幕上，你畫的對象最後會掩蓋那些你以前畫的畫。

Display Hierarchy

To manage the order in which DisplayObjects are drawn, DisplayObjects are organized in a hierarchy. This hierarchy determines which objects appear above other objects.

顯示層級

為了管理的順序繪製的DisplayObject，是有組織的DisplayObject層次結構中。這種層次結構決定了哪些對象出現上述其他對象。

Group Objects 組對象

The hierarchy is made possible by the existence of group objects. Group objects are a special kind ofDisplayObject that can have children. Group objects make it possible to organize your drawing so that you can build relationships between objects. One example of a group is a menu that pops up or slides down. The "menu" group would hold graphics, text, and buttons -- all children of the group.

該制度的存在成為可能的組對象。組對象是一種特殊的DisplayObject的，可以有孩子。組對象有可能組織你的繪圖，讓您可以建立對象之間的關係。一個例子，一組是一個彈出菜單或幻燈片了。 “菜單“小組將圖形，文字，按鈕 -所有兒童組。

You can make any DisplayObject a child of a group. The children are organized in an array, so the first child (index 1) is below the next child, and so on; the last child is always above all its siblings. You insert objects into a group using the group:insert() object method and you access the children by indexing into the group with integer indices (e.g. group[1] ):

你可以做任何DisplayObject的一個孩子一組。孩子們被組織在一個數組，所以第一個孩子（指數 1）低於下一個孩子，等等;最後一個孩子總是最重要的是它的兄弟姐妹。您插入的對象為一組使用 group:insert() 對象的方法，並訪問了兒童的成組索引整數索引（例如小組[1]）：

local square = display.newRect( 0, 0, 100, 100 )
local rect = display.newRect( 0, 0, 100, 100 )
local group = display.newGroup()
group:insert( square )
group:insert( rect )
assert( (group[1] == square) and (group[2] == rect) )

Stage Objects

Whenever you create a new object, it is implicitly added to a special group object that is at the top of the hierarchy. This group object is called the stage object (often referred to as the current stage). Every time you create a DisplayObject, it is implicitly added to the stage object. By default, it will add that object at the end of the child array and thus appear above all other child display objects. (Currently, there is only one stage in Corona. This stage represents the entire screen.) Once an object has been created it can be used as-is or moved to another group.

local square = display.newRect( 0, 0, 100, 100 )        -- Red square is
square:setFillColor( 255, 0, 0 )                                                -- at the bottom.
local circle = display.newCircle( 80, 120, 50 ) -- Green circle is
circle:setFillColor( 0, 255, 0 )                                                -- in the middle.
local rect = display.newRect( 0, 0, 100, 100 )          -- Blue rect is
rect:setFillColor( 0, 0, 255 )                                          -- at the top.
 
-- square,circle,rect all have same parent 方形，圓形，矩形都具有相同的父
local parent = square.parent
 
-- Move to top. Siblings at higher indices are above those at lower ones 移動到頂部。兄弟姐妹，高指數高於那些在較低的
parent:insert( square )         -- same as parent:insert( parent.length, square) 一樣的父母：插入（parent.length，方形）
 
-- Move below all other siblings 移動低於所有其他的兄弟姐妹
parent:insert( 1, circle ) --1是圖層編號，可以自訂

如果改成這樣

parent:insert( rect )  

parent:insert(7, square ) 

那 square 就是最上層

改成

parent:insert(5, square )

那 square 就往下移動了

Objects can also be moved within the group using object:toBack and object:toFront methods.

對象也可以移動集團內的使用object：toBack (往最後面移)和object：toFront (往最前面移)方法。

Drawing Cycle

The basic drawing model involves a cycle between executing Lua code and rendering objects in the display tree of the current stage object. During this cycle, the screen is only updated when objects in the display tree have changed. These changes occur by adding, removing, or changing properties of the child DisplayObjects.

This cycle may occur 30 or 60 times a second, depending on the frame rate setting in config.lua (seeFrame rate control). At the beginning of each cycle, an "enterFrame" event is dispatched to any registered listeners in your Lua code. Once all listeners have finished executing, the screen is updated.

繪圖週期

基本繪圖模型涉及週期之間執行 Lua代碼和渲染對象的顯示樹階段性目標。在這個週期中，當屏幕只更新顯示樹中的對象發生了變化。這些變化發生的加入，刪除或更改屬性兒童的DisplayObject。

這個週期可能會出現30或60次的速率，取決於幀速率設置在config.lua（見幀速率控制）。在每個週期的開始，一個“enterFrame“事件被分派到任何註冊的聽眾在你的Lua代碼。一旦所有的聽眾都執行完畢後，屏幕上會更新。

Screen Updates

The screen never updates while a block of your Lua code is executing. Therefore, if you modify a display object multiple times in a code block (e.g. the x position property), only the last change (e.g. the final value of x) will be reflected by the screen update.

Coordinates and Transforms 坐標與變換

坐標空間中定義的位置，所有圖紙發生。屏幕代表了相應的坐標系圖。所有內容必須最終被指定相對於原點在屏幕上。

通常，它是笨拙的術語來描述所有的屏幕坐標。因此，我們引入局部坐標的概念。每個顯示對象的工作在自己的局部坐標系統。繁重的轉換之間的顯示對象的本地坐標和屏幕坐標是為你。

這個過程的局部坐標之間的轉換和屏幕坐標而成為可能的數學變換，或轉換為短。坐標轉換從一個空間轉換到另一個。

Coordinates

A Cartesian coordinate system (also known as a rectangular coordinate system) is used to define position. Unlike standard Cartesian coordinates, the origin of the screen is located at the top-left corner so that positive y-coordinate values extend downward (positive x-values extend to the right as usual). All screen coordinates are defined relative to this origin.

坐標

一個直角坐標系（也稱為直角坐標系統）是用來定義的位置。不同於標準直角坐標系，原點在屏幕位於左上角，使正Y坐標值向下延伸（正x值延伸到右像往常一樣）。所有的屏幕坐標的定義相對這個原點。

Local coordinates allow you to manipulate geometric properties of a display object such as rotation in a more intuitive fashion. Every display object has an origin relative to its parent's. This origin essentially defines the position of the display object (relative to its parent). For example, if variable r was a rectangle, then it's origin/local-position would be (r.xOrigin, r.yOrigin).

局部坐標讓您操作幾何性質的，如旋轉顯示對象在一個更直觀的方式。每個顯示對象都有一個原始相對於其母公司。這個原點基本上定義顯示對象的位置（相對於其父）。例如，如果變量 r是一個長方形，那麼它的原產地/本地位置將是（r.xOrigin，r.yOrigin）。

When and object is created, it's coordinates are relative to the current stage (main screen). Adding a touch listener to the object will return touch locations that correspond to the location of the object on the screen. When the object is added to a group (not the current stage), the object's coordinates are relative to the group and not the screen. The touch locations returned by the object listener will no longer correspond to the x,y properties of by the touched object. The object.contentBounds API will map the object's coordinates back to the screen's coordinates.

當和對象被創建，它的坐標是相對於當前階段（主屏幕）。添加一個觸摸監聽的對象將返回到觸摸位置對應的對象的位置在屏幕上。當對象被添加到一個組（而不是目前的階段），該對象的坐標是相對於群組，而不是在屏幕上。觸摸地點返回的對象將不再監聽對應的x，y屬性所觸及的對象。該 object.contentBounds API將地圖對象的坐標回到屏幕的坐標。

Every object also has a local reference (or registration) point about which transformations such as rotations occur. The reference point is defined by two numbers (in the case of the rectangle r, these are r.xReference, r.yReference) which specify the location of the reference point relative to the local origin. By default, the reference point is the same as the local origin, i.e. the two numbers of the reference point are (0, 0).

每個對象也有一個本地引用（或註冊）的轉換點左右發生，如旋轉。參考點是指由兩個數字（在案件的矩形 r，這些都是r.xReference，r.yReference）的指定位置的參考點相對於本地的來源。默認情況下，參考點是一樣的地方來源，即兩個數字的參考點為（0，0）。

Changing Position of Objects 改變對象的位置

To change the position of a display object, you can either manipulate the ( xOrigin, yOrigin )properties or the ( x, y ) properties — typically you do the latter because that’s the same point about which scales and rotations occur.

要改變位置顯示對象，你可以操縱（xOrigin，yOrigin）屬性或的（x，y）的性能- 通常你做了後者，因為這是有關哪些相同點尺度和旋轉發生。

The ( xReference, yReference ) properties do not affect the position of a display object. Rather, they define where the reference point will be located, as this location affects scaling and rotation.

在（xReference，yReference）屬性不影響位置顯示對象。相反，它們定義參考點位置將位於，因為這個位置影響縮放和旋轉。

When an Display Object is created, the origin specifies the TopLeft corner of the object. After the object has been created, the reference point is now the center of the object and the x,y values will reference that point. The exception is display.newCircle, which is created with a center origin.

當顯示對象被創建時，左上角的起源指定角落的對象。之後，對象已經創建，參考點是目前中心的對象和X，Y值將引用了這一點。唯一的例外是display.newCircle，這是創建一個中心起點。

You can move the reference point back to the TopLeft with object:setReferencePoint(display.TopLeftReferencePoint )

您可以將參考點回左上與對象：setReferencePoint（display.TopLeftReferencePoint）

If you read the x,y reference points, they will be relative to the x,yOrigin points (center of the object). When the reference point is Center, the reference point is 0,0. When the reference point is TopLeft, the reference point is -w/2,-h/2 (1/2 the object's width and height).

如果你讀的x，y參照點，他們將相對於的X，yOrigin點（對象的中心）。當參考點為中心，參考點是0,0。當參考點是左上，參考點是 -w / 2，-h /2（1 /2的對象的寬度和高度）。

Transforms

Often, keeping track of transformations is a very error-prone and tricky business. This is because the order in which geometric transformations occurs determines the final position. For example, rotating an object and then scaling it (non-uniformly) will generate a different result from scaling that object first and then rotating.

變換

通常情況下，隨時追踪的轉換是一個很容易出錯，而且是棘手的事。這是因為其中的順序發生幾何變換決定了最終的位置。例如，旋轉一個對象，然後擴大它（非均勻）會產生不同的結果，從縮放對象，然後再旋轉。

To simplify things, we define an order of operations when transforming the object. These operations are all relative to the reference point of the display object. In this way, you are free to change the value of an object's position, rotation, and scale properties in any order you please; the resulting transformation remains consistent.

為了簡化問題，我們定義的命令行動時，改造的對象。這些操作都是相對於參考點的顯示對象。這樣，你可以自由地更改該值的對象的位置，旋轉和縮放屬性請您以任何順序，由此產生的變革保持一致。

This transformation is calculated by applying geometric operations in the following order:

這個轉變的計算方法是運用幾何運算的順序如下：

1. Scale the display object about its reference point using ( object.xScale, object.yScale ).
2. Rotate about the display object's reference point object.rotation degrees.
3. Move the object's origin (not its reference point) relative to the parent's by ( object.x, object.y ) in local coordinates.

1.縮放顯示對象的參考點使用（object.xScale，object.yScale）。
2.旋轉顯示對象的參考點是 object.rotation 度數。
3.移動對象的原點（而不是它的參考點）相對於父的由（object.x，object.y）在本地坐標。

Note: the methods object:scale(), object:rotate(), and object:translate() merely change the value of the underlying geometric properties. The order in which you call them does not affect the final result, so you should not think of them as matrix transformations.

注：方法 object:scale()，object:rotate(), and object:translate()只是改變了基本幾何性質。順序調用它們不會影響最終結果，所以你不應該把它們看作矩陣變換(這是3D才用的到)。

Object References 物件參考

Because objects can be reordered in the hierarchy, using integer indices to access children of groups is fragile. If you move a child above its sibling, all integer indices have to be updated. A simple solution to this is to store child display objects as a property of the parent group. This makes it easier to access those objects later.

因為對象可以在層次結構重新排序，使用整數索引來訪問的兒童群體是脆弱的。如果您移動一個孩子以上的兄弟姐妹，所有整數索引必須進行更新。一個簡單的解決方法是子顯示對象存儲為一個父組的屬性。這使得它之後更容易訪問這些對象。

Let’s consider a situation where we have images for the sun and the planets of our solar system. We want to put them all under one group. In this example, we have a table listing all the files and we’ve created a group that we’ll store the image objects in.

讓我們考慮一個情況，我們有圖片的太陽和行星，我們的太陽系。我們希望把他們都在一個組。在這個例子中，我們有一個表列出的所有文件，我們已經創建了一個小組，我們將存儲圖像對象英寸

local planetFiles = { sun="sun.png", mercury="mercury.png",
   venus="venus.png", earth="earth.png", mars="mars.png",
   jupiter="jupiter.png", saturn="saturn.png", neptune="neptune.png",
   uranus="uranus.png", pluto="pluto.png" }
 
local solarSystem = display.newGroup()

The next step is to create the image objects by iterating through the table planetFiles. We use a special iterator ipairs which will return both the property name and the image filename stored in the property of planetFiles. We use the filename to load the image; we use the property name to assign a property in group so we can easily refer to it later in the group without worrying about integer indices:

下一步是創建圖像對象的遍歷表 planetFiles。我們使用一個特殊的迭代器ipairs將同時返回屬性名稱和圖像文件存儲在財產 planetFiles。我們使用的文件名加載圖像，我們使用屬性名稱屬性分配組，以便我們能夠很容易地引用它後來在集團，而不必擔心整數指數：

-- Loop through all the files, load the image, assign property in the group for key,file in pairs( planetFiles ) do 遍歷所有文件，加載圖像，分配財產的組密鑰，文件中對（planetFiles）做
        -- key will be "sun", "mercury", etc.
        -- file will be "sun.png", "mercury.png", etc.
        local planet = display.newImage( file )
   solarSystem:insert( planet )
   solarSystem[key] = planet 
end
 
-- Afterwards: 之後
-- solarSystem.sun will refer to the image object for "sun.png", solarSystem.sun將參考圖像對象“sun.png“
-- solarSystem.mercury will refer to the image object "mercury.png",
-- etc.

Keep in mind that if you want to remove one of these objects, you need to do two things. First, you need to remove it from the display hierarchy. Second, you need to set the corresponding property of the parent group to nil (see Variable References).

請記住，如果你想刪除其中的這些對象，你需要做兩件事情。首先，你需要將其刪除從顯示的層次結構。其次，你需要設置相應的屬性母公司集團零（見變量的引用）。

Removing Objects Properly

Because devices have limited resources, it is important to remove display objects from the display hierarchy when you no longer use them. This helps overall system performance by reducing memory consumption (especially images) and eliminates unnecessary drawing.

When you create a display object, it is by default added to the root object of the display hierarchy. This object is a special kind of group object known as the stage object.

To properly remove an object so it no longer renders on screen, you need to remove the object explicitly from its parent. This removes the object from the display hierarchy. This can be done in either of the two following ways:

刪除對象正確

因為設備的資源有限，重要的是消除從顯示屏上顯示對象的層次結構，當您不再使用它們。這有助於降低整體系統性能的內存消耗（特別是圖片），並消除不必要的繪圖。

當你創建一個顯示對象，默認是添加到根對象的顯示層次。這個對象是一個特殊類型的組對象被稱為對象的舞台。

要正確地刪除對象，以便它不再呈現在屏幕上，你需要刪除的對象明確從其父。這將刪除該對象從顯示的層次結構。這可以在任一以下兩個方面：

image.parent:remove( image ) -- remove image from hierarchy
-- or --
image:removeSelf( ) -- same as above

However, this is not always sufficient to free the memory consumed by the image. To ensure that the image object is garbage collected properly, we need to eliminate all variable references to it as we will explain in the next section.

Note: Starting with build 316, removing a group with object:removSelf will remove the group and all it's children. This will free up all object listeners and texture memory used by the Display Objects in the group and convert the Display Object variables into simple Lua tables. Lua will garbage collect the remaining Lua variables if there are no other references to the those variables. (See the next section on Variable References.)

但是，這並不總是足以釋放內存消耗的圖像。為了確保圖像對象被垃圾收集正確，我們需要消除所有變量引用，我們將在下一節解釋。

注：啟動與 Build316，刪除一個組對象：removSelf將刪除組和所有它的孩子。這將釋放所有對象的聽眾和紋理內存使用的顯示組中的對象和顯示對象的變量轉換成簡單的Lua表。Lua 將垃圾收集餘下 Lua變量，如果沒有其他引用到這些變量。（請參閱下一節變量引用。）

Variable References

Even though a display object has been removed from the hierarchy, there are situations in which the object continues to exist. In our above example, the parent group solarSystem stores references to the image objects for planets as properties. So even after removing an image from the display hierarchy, we still need to ensure that solarSystem no longer refers to the image. To do this, we set the property to nil (we call this nil’ing out the property).

變量引用

即使顯示對象已被刪除從層次結構，在某些情況下該對象繼續存在。在我們上面的例子中，父集團 solarSystem存儲引用到行星的圖像對象的屬性。因此，即使取出後，從顯示的圖像層次，我們仍然需要確保 solarSystem不再引用的形象。要做到這一點，我們將該屬性設置為無（我們稱之為 nil'ing出屬性）。

local sun = solarSystem.sun
sun.parent:remove( sun ) -- remove image from hierarchy 刪除圖片的層次結構
solarSystem.sun = nil -- remove sun as a property of solarSystem 刪除 Sun作為財產 solarSystem

Generally speaking, if you inserted the display object as a table element (e.g. as a property of the table or as an array element), the display object will remain in existence even though it does not display to screen (see Object References). You have to nil out the property as in the above example.

一般來說，如果你插入的顯示對象為表元素（例如，作為一個屬性表或數組元素），顯示對象將繼續存在，即使它並不顯示到屏幕上（見對象引用）。你必須無出屬性，如上面的例子。

Similarly, if other variables that point to the display object, the display object cannot be freed as long as those objects continue to exist. For example, global variables are never freed so if a global variable points to a display object, it will continue to exist even if it is not in the display hierarchy. Here, you should also set the global variable to nil when you no longer need it.

同樣地，如果其他變量指向的顯示對象，顯示對象不能被釋放，只要這些物體繼續存在。例如，全局變量是永遠不會被釋放，所以如果一個全局變量指向一個顯示對象，它會繼續存在，即使它不是在顯示層次結構。在這裡，你還應該設置全局變量為 nil 當你不再需要它。

Another subtlety is when a function refers to a local variable outside its scope:

另一種微妙的是，當一個函數是指一個局部變量以外的範圍：

local sun = solarSystem.sun
 
function dimSun()
        sun.alpha = 0.5 -- sun was declared outside the function block 太陽是功能塊外聲明
end

In this case, there is still an outstanding reference to the image object inside this function. Because this function is global, the image object must remain in existence. There are 2 solutions: make the function non-global (i.e. local) or change the function so that no variables outside the function block are referenced. The latter is preferable and is also more general in that it can be applied to any display object:

在這種情況下，仍然是一個傑出的參考對象，這裡面的圖像功能。因為這個功能是全球性的，圖像對象必須繼續存在。有兩個解決方案：使函數非全局（即本地）或更改的功能，使沒有變量以外的功能模塊所引用。後者是可取的，也是更普遍，因為它可應用於任何顯示對象：

local sun = solarSystem.sun
 
function dim( object )
        object.alpha = 0.5
end

Common Pitfalls

A common mistake is to improperly remove all objects from a group. This typically happens when you write code that iterates through a group attempting to remove each child from the display hierarchy. It’s natural to iterate through the group in the forward direction. However, this can cause no end of confusion.

Continuing with our solar system example, consider the following where we attempt (incorrectly) to remove all the objects from the solar system.

常見缺陷

一個常見的錯誤是不正確刪除所有對象從一個組。這通常發生在你編寫的代碼，遍歷一組試圖刪除每一個孩子從顯示的層次結構。是很自然的遍歷集團在前進的方向。不過，這可能會導致沒有盡頭的混亂。

繼續與我們的太陽系例如，考慮下面，我們嘗試（錯誤）刪除所有的對象從太陽系。

for i=1,solarSystem.numChildren do
        local child = solarSystem[i]
        child.parent:remove( child )
end

The problem here is that we are modifying a collection (i.e. the group’s children array) as we iterate through that same collection. The result is we remove every other child. The easiest way to illustrate this is with a parallel example involving an array of integers:

這裡的問題是，我們正在修改一個集合（即集團的孩子陣列），因為我們遍歷相同的集合。其結果是，我們刪除所有其他的孩子。最簡單的方式來說明這是一個平行的例子涉及到數組的整數：

local array = {1,2,3,4,5,6,7,8,9,10}
print( table.concat( array, " " ) ) --> 1 2 3 4 5 6 7 8 9 10
 
for i=1,#array do
        table.remove( array, i )
end
 
print( table.concat( array, " " ) ) --> 2 4 6 8 10

The fix is to iterate backwards. 解決方法是向後遍歷。

for i=solarSystem.numChildren,1,-1 do
        local child = solarSystem[i]
        child.parent:remove( child )
end