2010年8月20日 星期五

Deprecated metadata tag



用法:
[Deprecated("string_describing_deprecation")]
[Deprecated(message="string_describing_deprecation")]
[Deprecated(replacement="string_specifying_replacement")]
[Deprecated(replacement="string_specifying_replacement", since="version_of_replacement")]

原文(引用自adobe flex4 help):
A class or class element marked as deprecated is one which is considered obsolete, and whose use is discouraged in the current release. While the class or class element still works, its use can generate compiler warnings

一個類別或是類別中的項目被標記成Deprecated表示此項目是過時的、廢棄的、不建議使用的,不鼓勵使用在當前的釋出版本。雖然被宣告廢棄的Class或Class中的項目仍然工作,但能讓編譯器產生警告提醒。

The mxmlc command-line compiler supports the show-deprecation-warnings compiler option, which, when true, configures the compiler to issue deprecation warnings when your application uses deprecated elements. The default value is true.

Insert the [Deprecated] metadata tag before a property, method, or class definition to mark that element as deprecated. The [Deprecated] metadata tag has the following options for its syntax when used with a class, property or method:
 
功用:

  • 標記已經廢棄的Class以免誤用,若使用編譯器會出現警告提醒。
範例:
//宣告method已經廢棄,並提示改用建議的method
package com
{
 import spark.components.Group;
 public class MyDeprecatedGroup extends Group
 {
  public function MyDeprecatedGroup()
  {
   super();
  }  
  private var _topGap:Number; 
  //宣告topGap廢棄,並建議使用topPixels
  [Deprecated(replacement="MyDeprecatedGroup.topPixels")] 
  public function set topGap(value:Number):void
  {
   _topGap = value;
  }
  public function get topGap():Number
  {
   return _topGap;
  }
 }
}  
//Application
<?xml version="1.0" encoding="utf-8"?> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
xmlns:s="library://ns.adobe.com/flex/spark" 
xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"
applicationComplete="application1_applicationCompleteHandler(event)" xmlns:com="com.*"
>
<fx:Script\>
<![CDATA[ 
]]>
</fx:Script>
<com:MyDeprecatedGroup>
 <com:topGap>1.0</com:topGap>  
</com:MyDeprecatedGroup>
</s:Application>   
訊息警告如下圖:
 
 
 
 
 
 

  • Event,Effect,Style,metadata tags也支援 deprecation功能

文件
The [Event], [Effect] and [Style] metadata tags also support deprecation. These tags support the following options for syntax:
 
在Event,Effect,Style的metadata tags中,也都支持deprecation的宣告,用法如下
 
用法
[Event(... , deprecatedMessage="string_describing_deprecation")]
[Event(... , deprecatedReplacement="change2")]
[Event(... , deprecatedReplacement="string_specifying_replacement", deprecatedSince="version_of_replacement")]

DefaultProperty metadata tag


用法:
[DefaultProperty("propertyName")]

原文:
The [DefaultProperty] metadata tag defines the name of the default property of the component when you use the component in an MXML file.

功用說明:
[DefaultProperty]標籤用來定義組件中的預設屬性,對應於MXML標籤檔上使用。

範例:
//這個範例將預設屬性改成selected,原本在toggleButtong上的預設屬性是label。
//myButton.as
package com
{

 import spark.components.ToggleButton;

 [DefaultProperty("selected")]
 public class myButton extends ToggleButton
 {
  public function myButton()
  {
   super();
  }
//mxml設定進來的值在此可以抓到並處理
  override public function set selected(value:Boolean):void
  {
   if(value != super.selected)
   super.selected = value;
  } 

 }

}
//mxml檔中使用ToggleButton與myButton來驗證結果
<s:Group layout="{new VerticalLayout()}">
<s:ToggleButton>true</s:ToggleButton> //預設屬性是label因此會出現true
<com:myButton>true</com:myButton>     //預設屬性是selected因此出現按下
</s:Group>












例外使用的狀況:
The one place where Flex prohibits the use of a default property is when you use the ActionScript class as the root tag of an MXML component. In this situation, you must use child tags to define the property, as the following example shows

主要是說,若是mxml做為根標籤,就無法直接在標籤中輸入文字使用預設值,而是須將改預設值名稱當成mxml標籤來呼叫使用。

當然這就是在說將Class做成mxml組件檔時的情境,範例如下:
//myButtonC.mxml
<?xml version="1.0" encoding="utf-8"?>
<com:myButton xmlns:fx="http://ns.adobe.com/mxml/2009" 
xmlns:s="library://ns.adobe.com/flex/spark" 
xmlns:mx="library://ns.adobe.com/flex/mx" xmlns:com="com.*">
<!--當成root標籤使用時,預設屬性設定改用標籤呼叫設定。-->
 <com:selected>true</com:selected>
</com:myButton> 

而這個組件放於Application上時,依然可以直接設定預設值如下:
<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
xmlns:s="library://ns.adobe.com/flex/spark" 
xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"
xmlns:com="com.*"
> 
<fx:Script>
<![CDATA[ 
import spark.layouts.VerticalLayout;
]]>
</fx:Script>
<s:Group layout="{new VerticalLayout()}">
<com:myButtonC>true</com:myButtonC>
</s:Group>
</s:Application>


參考
http://help.adobe.com/zh_CN/flex/using/WS2db454920e96a9e51e63e3d11c0bf680e1-7ffe.html

//查詢Creating a default property
http://help.adobe.com/zh_CN/flex/using/WS2db454920e96a9e51e63e3d11c0bf69084-79f7.html#WS2db454920e96a9e51e63e3d11c0bf69084-79fa

英文原文引用自adobe flex4 help文件