Menu
▾
▴
[Oorexx-svn] SF.net SVN: oorexx:[7415] docs/trunk/oodguide
|
From: <os...@us...> - 2012-01-08 22:50:49
|
Revision: 7415
http://oorexx.svn.sourceforge.net/oorexx/?rev=7415&view=rev
Author: osims
Date: 2012-01-08 22:50:43 +0000 (Sun, 08 Jan 2012)
Log Message:
-----------
Modified Paths:
--------------
docs/trunk/oodguide/Makefile
docs/trunk/oodguide/oodguide.xml
Added Paths:
-----------
docs/trunk/oodguide/appendix04.xml
Modified: docs/trunk/oodguide/Makefile
===================================================================
--- docs/trunk/oodguide/Makefile 2012-01-04 00:09:56 UTC (rev 7414)
+++ docs/trunk/oodguide/Makefile 2012-01-08 22:50:43 UTC (rev 7415)
@@ -48,6 +48,7 @@
appendix01.xml \
appendix02.xml \
appendix03.xml \
+ appendix04.xml \
Chapter02.xml \
Chapter03.xml \
Chapter04.xml \
Added: docs/trunk/oodguide/appendix04.xml
===================================================================
--- docs/trunk/oodguide/appendix04.xml (rev 0)
+++ docs/trunk/oodguide/appendix04.xml 2012-01-08 22:50:43 UTC (rev 7415)
@@ -0,0 +1,187 @@
+<!--#########################################################################
+ #
+ # Description: Open Object Rexx: ooDialog User Guide XML file.
+ #
+ # Copyright (c) 2011-2011, Rexx Language Association. All rights reserved.
+ #
+ # This program and the accompanying materials are made available under
+ # the terms of the Common Public License v1.0 which accompanies this
+ # distribution. A copy is also available at the following address:
+ # http://www.oorexx.org/license.html
+ #
+ # Redistribution and use in source and binary forms, with or
+ # without modification, are permitted provided that the following
+ # conditions are met:
+ #
+ # Redistributions of source code must retain the above copyright
+ # notice, this list of conditions and the following disclaimer.
+ # Redistributions in binary form must reproduce the above copyright
+ # notice, this list of conditions and the following disclaimer in
+ # the documentation and/or other materials provided with the distribution.
+ #
+ # Neither the name of Rexx Language Association nor the names
+ # of its contributors may be used to endorse or promote products
+ # derived from this software without specific prior written permission.
+ #
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+ # OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+ # OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ #
+ #########################################################################
+-->
+
+<!-- Appendix 04 - Dialog Sequences v00-01 08Jan12
+ Shows the methods invoked during dialog creation.
+
+ Changes:
+ v00-01 08Jan12: First version
+-->
+<appendix id="apx-dlgsequences">
+ <title id="dlgsequences.title">Dialog Creation Methods</title>
+ <indexterm><primary>Dialog</primary><secondary>Creation</secondary></indexterm>
+ <indexterm><primary>Methods</primary><secondary>Dialog Creation</secondary></indexterm>
+ <para>This appendix provides a programmer's aide-memoire for the methods required to create and
+ set up a dialog using one of the more usual superclasses - <computeroutput>UserDialog</computeroutput>,
+ <computeroutput>RcDialog</computeroutput> and <computeroutput>ResDialog</computeroutput>.
+ Menu creation is included even though this is technically quite separate from
+ dialog creation.</para>
+ <para>The following table shows, for each of the three main dialog types, the method
+ invocations that the programmer must code and the methods (invoked by ooDialog-provided
+ superclasses as part of the dialog creation framework) that the programmer must provide. </para>
+<table id="dlgcreation" frame="all"><title>Dialog Creation - Method Sequences</title>
+<tgroup cols="5">
+ <colspec colnum="1" colname="c1" colwidth="81.75pt"/>
+ <colspec colnum="2" colname="c2" colwidth="141.75pt"/>
+ <colspec colnum="3" colname="c3" colwidth="137.25pt"/>
+ <colspec colnum="4" colname="c4" colwidth="140.25pt"/>
+ <colspec colnum="5" colname="c5" colwidth="114.75pt"/>
+<thead>
+ <row>
+ <entry><literallayout> Methods
+ / ~Invocations</literallayout></entry>
+ <entry> UserDialog</entry>
+ <entry> RcDialog</entry>
+ <entry> ResDialog</entry>
+ <entry>Comment</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><emphasis role="italic"> .Dlg~new(...)</emphasis></entry>
+ <entry> Yes.</entry>
+ <entry> Yes.</entry>
+ <entry> Yes.</entry>
+ <entry><literallayout> Class
+ Method</literallayout></entry>
+ </row>
+ <row>
+ <entry><emphasis role="italic"> init</emphasis></entry>
+ <entry> Yes.</entry>
+ <entry>
+ <literallayout> Yes.
+ Create Menubar using
+ <emphasis role="italic">.ScriptMenuBar~new</emphasis></literallayout>
+ </entry>
+ <entry> Yes.</entry>
+ <entry><literallayout> Must be passed to the
+ superclass using
+ <emphasis role="italic">forward class (super)
+ - continue</emphasis> </literallayout></entry>
+ </row>
+ <row>
+ <entry><emphasis role="italic"> defineDialog</emphasis></entry>
+ <entry><literallayout> Yes.
+ Programmer creates the
+ Dialog Template using
+ <emphasis role="italic">self~create...(...)</emphasis></literallayout></entry>
+ <entry><literallayout> Optional.
+ Dialog Template is defined
+ by the *.rc file, but additional
+ controls (or menu items)
+ can be added here.</literallayout></entry>
+ <entry><literallayout> No.
+ Not invoked - the Dialog
+ Template is defined by
+ the *.dll file - so controls
+ or menu items cannot be
+ added.</literallayout></entry>
+ <entry><literallayout> Called by super's <emphasis role="italic">init</emphasis>
+ method (but not
+ for <computeroutput>ResDialog</computeroutput>s)
+
+ Purpose: create the
+ Dialog Template. </literallayout></entry>
+ </row>
+ <row>
+ <entry><emphasis role="italic"> dlg~execute</emphasis></entry>
+ <entry> Yes.</entry>
+ <entry> Yes. </entry>
+ <entry> Yes. </entry>
+ <entry><literallayout> Creates the Underlying
+ Dialog based on the
+ Dialog Template </literallayout></entry>
+ </row>
+ <row>
+ <entry><emphasis role="italic"> initDialog</emphasis></entry>
+ <entry><literallayout> Create "proxies" for controls
+ and initialize them using
+ <emphasis role="italic">proxy = self~new...(...)</emphasis>
+
+ Create Menubar
+ <emphasis role="italic">.BinaryMenuBar~new()</emphasis></literallayout></entry>
+
+ <entry> <literallayout> Create "proxies" for controls
+ and initialize them using
+ <emphasis role="italic">proxy = self~new...(...)</emphasis>
+
+ Attach Menubar</literallayout></entry>
+ <entry><literallayout> Create "proxies" for controls
+ and initialize them using
+ <emphasis role="italic">proxy = self~new...(...)</emphasis>
+
+ Create Menubar
+ <emphasis role="italic">.BinaryMenuBar~new()</emphasis></literallayout>
+ </entry>
+ <entry><literallayout> Called automatically
+ after <emphasis role="italic">~execute</emphasis> is
+ invoked.</literallayout>
+ </entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+ <para>First, as for all ooRexx objects, the <emphasis role="italic">~new</emphasis> method creates
+ an instance of a dialog, and the <emphasis role="italic">init</emphasis> method is then
+ invoked on the new instance, which must invoke the superclass' <emphasis role="italic"
+ >init</emphasis> using <emphasis role="italic">forward class (super) continue</emphasis>.
+ For <computeroutput>RcDialog</computeroutput> subclasses, a menubar could be created in this
+ method, but could also be created later.</para>
+ <para>The <emphasis role="italic">defineDialog</emphasis> method (see section 8.7 of the ooDialog
+ Reference) is invoked automatically by the superclass' <emphasis role="italic">init</emphasis>
+ method. The <emphasis role="italic">defineDialog</emphasis> method provides for the creation
+ of the "Dialog Template" (see ooDialog Reference section 2.3.2) - that is, the layout of
+ controls on the dialog. The dialog template for an <computeroutput>RcDialog</computeroutput>
+ is normally fully-defined by the *.rc file, but can optionally be enhanced here. However, the
+ template for an <computeroutput>RcDialog</computeroutput>is fully-defined in the *.dll file,
+ and so <emphasis role="italic">defineDialog</emphasis> is not sent.</para>
+ <para>On exit from the <emphasis role="italic">defineDialog</emphasis> method, the dialog
+ template is established. </para>
+ <para>The "underlying dialog" (see ooDialog Reference section 2.3.11) is then created and
+ surfaced (made visible to the user) by invoking the superclass' <emphasis role="italic"
+ >execute</emphasis> method (see ooDialog Reference section 3.7.5). </para>
+ <para>Finally, the <emphasis role="italic">initDialog</emphasis> method (see ooDialog Reference
+ section 3.7.7) is provided for the programmer to initialize the various controls - e.g. set an
+ edit control to its initial data value, or select a radio button. This is done by creating
+ "proxies" for those controls that need to be manipulated within the program, typically using
+ <emphasis role="italic">proxy = self~new...(...)</emphasis> statements. </para>
+
+</appendix>
+
Modified: docs/trunk/oodguide/oodguide.xml
===================================================================
--- docs/trunk/oodguide/oodguide.xml 2012-01-04 00:09:56 UTC (rev 7414)
+++ docs/trunk/oodguide/oodguide.xml 2012-01-08 22:50:43 UTC (rev 7415)
@@ -11,6 +11,7 @@
<!ENTITY appendix01 SYSTEM "appendix01.xml">
<!ENTITY appendix02 SYSTEM "appendix02.xml">
<!ENTITY appendix03 SYSTEM "appendix03.xml">
+<!ENTITY appendix04 SYSTEM "appendix04.xml">
<!ENTITY notices SYSTEM "../shared/notices.xml">
<!ENTITY cpl SYSTEM "../shared/CPLv1.0.xml">
<!ENTITY gethelp SYSTEM "../shared/gethelp.xml">
@@ -78,6 +79,7 @@
&appendix01; <!-- First appendix -->
&appendix02; <!-- Second appendix -->
&appendix03; <!-- Third appendix -->
+&appendix04; <!-- Fourth appendix -->
¬ices; <!-- Notices -->
&cpl; <!-- CPL -->
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|