cvs: php-gtk-doc /manual/zh_cn/tutorials changes.xml

http://cvs.php.net/viewvc.cgi/php-gtk-doc/manual/zh_cn/tutorials/changes.xml?view=markup&rev=1.1
Index: php-gtk-doc/manual/zh_cn/tutorials/changes.xml
+++ php-gtk-doc/manual/zh_cn/tutorials/changes.xml
<?xml version="1.0" encoding="utf-8" ?>
<!-- EN-Revision: 1.6 Maintainer: mikespook Status: translating -->
<!-- $Revision: 1.1 $ -->
<chapter id="tutorials.changes">
 <title>PHP-GTK 1 之后的变化</title>

 <sect1>
  <title>关于本指南</title>
  <simpara>
   本指南将介绍 PHP-GTK 1 和 PHP-GTK 2
   之间的不同：发生变化的，新增加的以及不再使用的。
  </simpara>
  <simpara>
   虽然 PHP-GTK 2 尝试向后兼容，但是 GTK 2 本身经常不能向后兼容，
   PHP-GTK 2 也无力回天。有很多内容是没有变化的，
   但是在你迁移到第二版的时候必须了解一些关键的细微变化。
  </simpara>
 </sect1>

 <sect1 id="tutorials.changes.loadmodule">
  <title>加载 php_gtk 模块</title>
  <para>
   在 PHP-GTK 1 中，你并不知道 php－gtk 模块是否已经由
   <filename>php.ini</filename>
   自动加载，还是设置有错误（经常发生！），你不得不手工加载它们：
   <programlisting role="php">
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
     href="&directory.examples;/tutorials/changes/extension_load.phpw" parse="text">
     <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
    </xi:include>
   </programlisting>
  </para>

  <para>
   在 PHP 5 中，已经不再推荐使用 <literal>dl()</literal>
   加载模块。意味着虽然这种方式仍然可以使用，但是不鼓励人们继续使用它。
   那么，你可以假定 PHP-GTK 已经加载。或者，你希望捕获所有可能的错误，检查
   PHP-GTK 模块，当其不存在时抛出一个错误：
   <programlisting role="php">
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
     href="&directory.examples;/tutorials/changes/extension_check.phpw" parse="text">
     <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
    </xi:include>
   </programlisting>
  </para>
 </sect1>

 <sect1 id="tutorials.changes.references">
  <title>对象引用（&amp; 符号）</title>
  <para>
   支持面向对象是在 PHP 4 中才出现的，因此相比其他支持 OO
   的语言来说还非常简陋，比如 Java。当赋值变量时，不要复制一个 GTK
   对象，而是传递一个引用。
   <programlisting role="php"><![CDATA[
//PHP 4: 使用默认方式复制
$a = new GtkLabel();
$a->set_text('1');
$b = $a;
$b->set_text('2');
echo $a->get();//still 1
]]></programlisting>
    当赋值变量时，为了不复制一个对象你必须用引用符号 &amp;：
   <programlisting role="php"><![CDATA[
//PHP 4: 建立引用
$a = new GtkLabel();
$a->set_text('1');
$b = &$a;
$b->set_text('2');
echo $a->get();//is 2 now
]]></programlisting>
   无论如何，下面的情况一个对象的副本 <emphasis>都会</emphasis>
   被创建：在构造函数中。为了完全正确的使用引用，特别是针对 GTK 元件，你必须：
   <programlisting role="php"><![CDATA[
//PHP 4: 实例化引用
$a = &new GtkLabel();
]]></programlisting>
  </para>

  <para>
   在 PHP 5 中，已经发生了变化：传递引用已经成为默认的操作——不再需要使用引用符号！
   下面的脚本工作于 PHP 5 的 PHP-GTK 2 下，没有任何问题：
   <programlisting role="php">
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
     href="&directory.examples;/tutorials/changes/ampersand_php5.phpw" parse="text">
     <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
    </xi:include>
   </programlisting>
  </para>

  <para>
   同样在回调函数中，也不再需要使用引用符号！而在 PHP 4 和 GTK 1
   中你必须这样做：
   <programlisting role="php"><![CDATA[
$window->connect_object('destroy', array(&$object, 'function'));
]]></programlisting>
   在 PHP 5 和 GTK 2 中你只需要去除 &amp;：
   <programlisting role="php"><![CDATA[
$window->connect_simple('destroy', array($object, 'function'));
]]></programlisting>
  </para>
 </sect1>

 <sect1 id="tutorials.changes.constants">
  <title>GTK 常量</title>

  <para>
   GTK + 使用了大量的常量。在 PHP-GTK 1
   中，它们被定义成全局范围而你可以通过下面的方法访问：
   <programlisting role="php"><![CDATA[
echo GTK_WIN_POS_CENTER;
]]></programlisting>
   如果你在 PHP-GTK 2 中执行上面的代码，下面的错误会被抛出：
  </para>

  <screen><![CDATA[
PHP Notice:  Use of undefined constant GTK_WIN_POS_CENTER -
assumed 'GTK_WIN_POS_CENTER' in /path/to/file.php on line 23
]]></screen>

  <para>
   问题在于原先的值不再使用（在 PHP-GTK 1 中
   <literal>GTK_WIN_POS_CENTER</literal> 表示整数 <literal>1</literal>
   ）。字符串 <literal>"GTK_WIN_POS_CENTER"</literal> 在 PHP-GTK 2
   中可能破坏你的代码。（有问题的翻译：The string literal itself,
   <literal>"GTK_WIN_POS_CENTER"</literal>, is all PHP-GTK 2 sees
   - which is likely to break your code.）
  </para>

  <para>
   在 PHP 5 中支持静态类常量，所以决定不再使用 PHP-GTK
   常量污染全局名字空间。它们被定义在类
   <literal>Gtk</literal>，<literal>Gdk</literal> 或其他类中。
  </para>

  <para>
   简单的说，（在多数情况下）你需要做的是替换第一个下划线 <literal>_</literal>
   为两个 :，这样 PHP-GTK 1 中的 <literal>GTK_WIN_POS_CENTER</literal> 在
   PHP-GTK 2 中就变为 <literal>Gtk::WIN_POS_CENTER</literal>。
  </para>

  <para>
   同时，注意新的代码样式。考虑到类常量代替了全局常量，在官方发布的 PHP-GTK 2 文档和代码中
   <literal>Gtk</literal>，<literal>Gdk</literal>，<literal>Pango</literal>
   和 <literal>Atk</literal> 只有首字母应当大写。
  </para>
 </sect1>

 <sect1 id="tutorials.changes.connect">
  <title>连接信号处理</title>

  <para>
   在 PHP-GTK 1 的代码中绑定信号到指定的函数上，你可以使用：
   <function class="GtkObject">connect</function>,
   <function class="GtkObject">connect_object</function>,
   <function class="GtkObject">connect_after</function> or
   <function class="GtkObject">connect_object_after</function>.
   <literal>connect_object</literal> 的功能，第一眼看上去特别的不清晰。
  </para>

  <para>
   随着 GTK 信号 API 的一些变化，决定在 PHP-GTK 2 中修改
   <literal>connect_object</literal> 为 <function
    class="GtkObject">connect_simple</function> 同时修改
   <literal>connect_object_after</literal> 为 <function
    class="GtkObject">connect_simple_after</function>。由于对象本身无需参数，
   <emphasis>Simple</emphasis> 这里意味着几乎没有参数， 
   <literal>connect_object</literal> 有这个意思，但不够明确。
  </para>
 </sect1>

 <sect1 id="tutorials.changes.deprecated">
  <title>废弃的元件</title>

  <simpara>
   GTK 2 有许多新的元件类。多数新类比起旧的类表现得更好且有所不同；
   相比新的类来说，旧的元件不再推荐使用。
  </simpara>

  <simpara>
   为了向后兼容，旧的元件仍然可以使用，但是可能在 GTK 3 中被移除或出现其他情况。
   这意味着你无需完全重新编写你原有的程序，在一点改动之后可以使用它们。
   然而，你的确不应当在新的代码中再使用废弃的元件。千万不要这么做。
  </simpara>

<!-- xsltproc segfaults when I uncomment the table!
     Because of that I used the unordered list.
  <table>
   <title>List of deprecated widgets</title>
   <tgroup>
    <thead>
     <row>
      <entry>Old widget class</entry>
      <entry>New widget class</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><classname>GtkCList</classname></entry>
      <entry><classname>GtkTreeView</classname> with <classname>GtkListStore</classname></entry>
     </row>
     <row>
      <entry><classname>GtkCTree</classname></entry>
      <entry><classname>GtkTreeView</classname> with <classname>GtkTreeStore</classname></entry>
     </row>
     <row>
      <entry><classname>GtkPixmap</classname></entry>
      <entry><classname>GtkImage</classname> with <classname>GdkPixbuf</classname></entry>
     </row>
    </tbody>
   </tgroup>
  </table>
-->

  <para>
   <itemizedlist>
    <title>废弃的元件列表</title>
    <listitem>
     <classname>GtkCList</classname> 和 <classname>GtkList</classname> =>
     <classname>GtkTreeView</classname> 和 <classname>GtkListStore</classname>
    </listitem>
    <listitem>
     <classname>GtkCTree</classname> =>
     <classname>GtkTreeView</classname> 和 <classname>GtkTreeStore</classname>
    </listitem>
    <listitem>
     <classname>GtkCombo</classname> 和 <classname>GtkOptionMenu</classname> =>
     <classname>GtkComboBox</classname> 和 <classname>GtkTreeModel</classname>
    </listitem>
    <listitem>
     <classname>GtkItemFactory</classname> =>
     <classname>GtkUIManager</classname>
    </listitem>
    <listitem>
     <classname>GtkOldEditable</classname> =>
     <classname>GtkEditable</classname>
    </listitem>
    <listitem>
     <classname>GtkPixmap</classname> and <classname>GtkPreview</classname> =>
     <classname>GtkImage</classname> 和 <classname>GdkPixbuf</classname>
    </listitem>
    <listitem>
     <literal>GtkText</literal> =>
     <classname>GtkTextView</classname> 和 <classname>GtkTextBuffer</classname>
    </listitem>
   </itemizedlist>
   </para>
  <para>
   <itemizedlist>
    <title>废弃的方法列表</title>
    <listitem>
     <function class="GtkWindow">set_policy</function> => 
     <function classname="GtkWindow">set_resizable</function>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   这个列表可能不完整。如果你发现有废弃的元件没有罗列其中，
   请通知 <ulink url="mailto:[email protected]">php-gtk-doc</ulink>。
  </simpara>
 </sect1>

</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->