From: <mie...@us...> - 2011-07-19 20:09:33
|
Revision: 7055 http://oorexx.svn.sourceforge.net/oorexx/?rev=7055&view=rev Author: miesfeld Date: 2011-07-19 20:09:23 +0000 (Tue, 19 Jul 2011) Log Message: ----------- 3368833 Chap 4 and 5. Patch supplied by Oliver Sims Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/oodguide.xml Added Paths: ----------- docs/trunk/oodguide/Chapter05.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2011-07-18 15:26:15 UTC (rev 7054) +++ docs/trunk/oodguide/Chapter04.xml 2011-07-19 20:09:23 UTC (rev 7055) @@ -257,7 +257,7 @@ layout from a resource script file that is human-readable (using a text editor). RcDialog is one of two important ooDialog classes that use resource scripts; the other is <computeroutput>ResDialog</computeroutput>, which uses a binary (compiled) resource file as - illustrated in the last section of this chapter. More information on resource files can be + discussed in the next chapter. More information on resource files can be found in chapter 6 of the ooDialog Reference. </para> <para>View classes can be seen as consisting of three major parts: setting up the dialog window, specifying the "active" controls (i.e. controls that need to be accessed programmatically), @@ -269,32 +269,41 @@ comments displayed in the command prompt window, as follows: <programlisting> <![CDATA[ D:\...\Exercise04a>startup - StartCustomerView Routine-01: .CustomerView~new... - CustomerView-init-01 - CustomerView-createMenuBar-01 - StartCustomerView Routine-02: dlg~activate... - CustomerView-activate-01 - CustomerView-initDialog-01 + StartCustomerView Routine-01: Start. + CustomerView-init-01. + CustomerView-createMenuBar-01. + StartCustomerView Routine-02: dlg~activate. + CustomerView-activate-01. + CustomerView-initDialog-01. ]]> </programlisting>These comments trace the process of establishing a dialog to the point of making the window visible - in other words, setting up the dialog. One routine and four methods are involved, as follows: <orderedlist> <listitem> - <para>The routine in <computeroutput>CustomerView.rex</computeroutput> creates an - instance of the <computeroutput>CustomerView</computeroutput> class that's a subclass - of <computeroutput>RcDialog</computeroutput>.</para> + <para>The <computeroutput>StartCustomerView</computeroutput> routine + in <computeroutput>CustomerView.rex</computeroutput> first stores the resource header file + file <computeroutput>CustomerView.h</computeroutput> in the + <indexterm><primary>.Application object</primary></indexterm> + <computeroutput>.Application</computeroutput> object using the + <emphasis role='italic'>useGlobalConstDir</emphasis> method. The header + file provides the correspondance between numeric + and symbolic IDs, so that the numeric IDs in the resource DLL can be + mapped to symbolic IDs used in the program.(See sections 10.1 and 10.5 of the + ooDialog Reference for further information on .Application.) Then an + instance of the <computeroutput>CustomerView</computeroutput> class (a subclass + of <computeroutput>RcDialog</computeroutput>) is created.</para> </listitem> <listitem> <para>In the <emphasis role="italic">init</emphasis> method of the new view instance, first the superclass is invoked (this is an ooDialog requirement), and then the - <emphasis role="italic">createMenuBar</emphasis> method is called. Note that if the - menubar creation fails, then <emphasis role="italic">initCode</emphasis> is an - attribute of a <computeroutput>.Dialog</computeroutput> instance. It represents the - success of initialization of a dialog object. For a dialog object, after the <emphasis - role="italic">init</emphasis> method has executed the <emphasis role="italic" - >initCode</emphasis> attribute will be zero if the dialog initialization detected no - errors. The attribute will be non-zero if initialization failed or an error was - detected. </para> + <emphasis role="italic">createMenuBar</emphasis> method is called. If the + menubar creation fails, then the dialog's <emphasis role="italic">initCode</emphasis> + attribute is set to 1 (initCode is an attribute of a <computeroutput>.Dialog</computeroutput> + instance and represents the success of initialization of a dialog object). + After the <emphasis role="italic">init</emphasis> method has executed the + <emphasis role="italic">initCode</emphasis> attribute will be zero + if the dialog initialization detected no errors, and non-zero if + initialization failed or an error was detected.</para> </listitem> <listitem> <para>The <emphasis role="italic">createMenuBar</emphasis> method then creates a menubar @@ -302,8 +311,10 @@ ooDialog Reference), referring to the menubar's ID in the .rc file. Note that after creation, the menubar is just another object, and is not yet associated with the dialog. The code at this point boldly assumes that the menubar instance was - successfully created (not really best practice) and returns to the <emphasis - role="italic">init</emphasis> method and from there back to the ...</para> + successfully created. This is not really best practice; however if initialization fails + the failure will be immediately visible - or rather invisible in that the + dialog will fail to appear!. Control then returns to the + <emphasis role="italic">init</emphasis> method and from there back to the ...</para> </listitem> <listitem> <para>...<computeroutput>StartCustomerView</computeroutput> routine, which invokes the @@ -324,12 +335,10 @@ <para>The above process requires four methods and a total of 19 ooRexx statements including the <computeroutput>::Method</computeroutput> statements but excluding the <emphasis role="italic">say</emphasis> instructions. And if we didn't care too much for effective - program structure or error checking, it could be squished down to just nine instructions as + program structure or error checking, it could be squished down to just ten instructions as follows: <programlisting> <![CDATA[ - ::ROUTINE startCustomerView PUBLIC - dlg = .CustomerView~new("customerView.rc", IDD_DIALOG1, dlgData., "customerView.h") ::CLASS CustomerView SUBCLASS RcDialog PUBLIC ::METHOD init forward class (super) continue @@ -337,17 +346,22 @@ ::METHOD initDialog menuBar = .scriptMenuBar~new("CustomerView.rc", "IDR_MENU1", self, , , .true) menuBar~attachTo(self) + ::ROUTINE startCustomerView PUBLIC + .application~useGlobalConstDir("O", "CustomerView.h") + dlg = .CustomerView~new("customerView.rc", "IDD_DIALOG1") ]]> </programlisting> And if the <computeroutput>::class</computeroutput>, <computeroutput>::method</computeroutput>, and <computeroutput>::routine</computeroutput> - directives are excluded, only five statements are required: <emphasis role="italic">~new</emphasis> + directives are excluded, only six statements are required: defining + <computeroutput>CustomerView.h</computeroutput> as the *.h file, the + <emphasis role="italic">.CustomerView~new</emphasis> to create a dialog instance, call super in the <emphasis role="italic">init</emphasis> - method, do <emphasis role="italic">execute("SHOWTOP")</emphasis>, create a menubar, - and attach the menubar to self.</para> + method, issue <emphasis role="italic">execute("SHOWTOP")</emphasis>, create a menubar, + and attach the menubar to the dialog.</para> <para> In other words, dialogs of significant complexity can be created and displayed with - only five executable statements. And that is the real power of resource dialogs. + only six executable statements. And that is the real power of resource dialogs. </para> </section> @@ -636,29 +650,5 @@ </section> <!-- end of section 4.3 --> -<section id="chap04-resfile"><title>Using Binary Resource Files</title> <!-- section 4.4 --> -<para> Notes: </para> -<para> - For a ResDialog, you use a resource-only DLL. A resource-only DLL is a resource script - (.rc) file compiled into binary format. ResEdit is capable of doing this compilation, with - two caveats: - <itemizedlist> - <listitem> - <para>You have to do it from the command line:</para> - <para><computeroutput>resedit -convert UserMenuBar.rc UserMenuBar.dll</computeroutput></para> - </listitem> - <listitem> - <para>It only works for 32-bit DLLs - that is, you need to be on a 32-bit system.</para> - </listitem> - <listitem> - <para>To work, the *.h file and any *.bmp files must be in the same directory - as the .rc file. If present and referenced by the .rc file, any *.bmp files - are also compiled into the DLL. At run-time, all that is needed is the DLL - and the.h file.</para> - </listitem> - </itemizedlist> -</para> -</section> - </chapter> Added: docs/trunk/oodguide/Chapter05.xml =================================================================== --- docs/trunk/oodguide/Chapter05.xml (rev 0) +++ docs/trunk/oodguide/Chapter05.xml 2011-07-19 20:09:23 UTC (rev 7055) @@ -0,0 +1,115 @@ +<!--######################################################################### + # + # 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. + # + ######################################################################### +--> + +<!-- Chapter05 version 00-01 - Using Binary Resource Dialogs + 4.1 Naming and Coding Conventions + 4.1.1 Naming Conventions + 4.1.2 Coding Conventions + 4.2 Resource Scripts and a Resource File Editors + 4.3 Coding an RcDialog Class + 4.3.1 Setting Up the Dialog + 4.3.2 Handling User Events + 4.3.3 Application Data and Function + 4.4 Coding a ResDialog Class + +--> + +<chapter id="chapFive"><title>Using Binary Resource Dialogs</title> +<indexterm><primary>Binary Resource Dialogs</primary></indexterm> +<indexterm><primary>ProductView component</primary></indexterm> +<para>In this chapter ...</para> + +<section id="chap04-resfile"><title>Coding a ResDialog Class</title> +<para>The ooDialog <computeroutput>ResDialog</computeroutput> class requires a resource-only + DLL. A resource-only DLL is a resource script (.rc) file compiled into binary format. + ResEdit is capable of doing this compilation, with three caveats: + <itemizedlist> + <listitem> + <para>It must be done from the command line:</para> + <para><computeroutput>resedit -convert filename.rc filename.dll</computeroutput></para> + </listitem> + <listitem> + <para>It only works for 32-bit DLLs - that is, you need to be on a 32-bit system.</para> + </listitem> + <listitem> + <para>At compile time, the *.h file and any *.bmp files must be in the same directory as + the .rc file. If present and referenced by the .rc file, the *.bmp files are compiled + into the DLL. </para> + </listitem> + </itemizedlist> + </para> + <para>At run-time, all that is needed for a ResDialog class is the DLL and the.h file.</para> + <para>Exercise04b contains a Product View component, the main class + <computeroutput>ProductView</computeroutput> being a subclass of the ooDialog + <computeroutput>ResDialog</computeroutput> class. Try running + <computeroutput>Startup.rex</computeroutput>. Things to include:</para> + <para>- Update Chap 3 to explain .application - or find out how not to use it - also check on + code snippets that they're still OK.</para> + <para>- use of .Application~constdir so can use symbolic resource names in menus (???).</para> + <para>- Menu created after initDialog (unlike RcDialog) - diff between them.</para> + <para>- Autodetect - if omit, get blank fields because ... autoconnect, without dlgData, sets + to default value. (ref to app 2 dlgdata)</para> + <para>- The About Box and the things in it - an image, how get dbl-click, etc.</para> + <para>- Class-based initiation - no routine.</para> + <para>- radio buttons and style for group box to make them auto</para> + <para>- Disallow close</para> + <para>- User vs App data (like diff bewteen app and DB)</para> + <para>- decEdit</para> + <para>- How to handle cancel and also block unintended keystrokes (e.g. hitting Esc)</para> + <para>- About box</para> + <para>- Dbl-click on image (in about box)</para> + <para>- Menus - method is the text, not the symbolic ID (if not done in Chap 3).</para> + <para>- Sequence of operation - different from RcDialog (menu created at diff place)</para> + <programlisting> + <![CDATA[ + d:\development\oodUserGuide\WorkingExercises\exercise04b>startup +ProductView-init. +ProductView-initAutoDetection. +ProductView-activate. +ProductView-initDialog +ProductView-getInitData-01. +ProductView-showData-01. +]]> + </programlisting> + <para><emphasis role="bold"><emphasis role="italic">Problems</emphasis></emphasis></para> + <para>Adding IDB_PROD_ICON to the execute stmt does not display the icon in top-left of window.</para> + </section> + +</chapter> Property changes on: docs/trunk/oodguide/Chapter05.xml ___________________________________________________________________ Added: svn:eol-style + native Modified: docs/trunk/oodguide/oodguide.xml =================================================================== --- docs/trunk/oodguide/oodguide.xml 2011-07-18 15:26:15 UTC (rev 7054) +++ docs/trunk/oodguide/oodguide.xml 2011-07-19 20:09:23 UTC (rev 7055) @@ -6,6 +6,7 @@ <!ENTITY chapter2 SYSTEM "chapter02.xml"> <!ENTITY chapter3 SYSTEM "chapter03.xml"> <!ENTITY chapter4 SYSTEM "Chapter04.xml"> +<!ENTITY chapter5 SYSTEM "Chapter05.xml"> <!ENTITY appendix01 SYSTEM "appendix01.xml"> <!ENTITY appendix02 SYSTEM "appendix02.xml"> <!ENTITY notices SYSTEM "../shared/notices.xml"> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |