From: <os...@us...> - 2012-01-26 11:15:53
|
Revision: 7456 http://oorexx.svn.sourceforge.net/oorexx/?rev=7456&view=rev Author: osims Date: 2012-01-26 11:15:42 +0000 (Thu, 26 Jan 2012) Log Message: ----------- fix copyright on Chapter04, minor update to Chap05. Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/Chapter05.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-01-25 12:21:52 UTC (rev 7455) +++ docs/trunk/oodguide/Chapter04.xml 2012-01-26 11:15:42 UTC (rev 7456) @@ -2,7 +2,7 @@ # # Description: Open Object Rexx: ooDialog User Guide XML file. # - # Copyright (c) 2011-2011, Rexx Language Association. All rights reserved. + # Copyright (c) 2011-2012, 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 @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter04 - Using Resource Dialogs v00-08 25Jan12 +<!-- Chapter04 - Using Resource Dialogs v00-09 25Jan12 4.1 Naming and Coding Conventions 4.1.1 Naming Conventions 4.1.2 Coding Conventions @@ -56,6 +56,7 @@ v00-07 17Aug11: Updated to reflect use of new .Application~setDefaults in CustomerView code. v00-08 25Jan12: A number of individually minor corrections. + v00-09 25Jan12: Oops - forgot about hitting Esc and disappearing the dialog. --> <chapter id="chapFour"> <title>Using Resource Dialogs</title> @@ -644,43 +645,50 @@ <![CDATA[ custControls[ecCustName]~setReadOnly(.false) ]]> - </programlisting>Pushbuttons are enabled by invoking <emphasis role="italic" - >enableControl</emphasis> on the dialog, the parameter being the control's symbolic ID - as shown in the first statement below. The second statement below puts focus on the - push-button - in this case by invoking the <emphasis role="italic">state</emphasis> - method of the control object. Finally, the cursor is placed in the Customer Name edit - control by invoking the dialog's <emphasis role="italic">focusControl</emphasis> method. <programlisting> - <![CDATA[ + </programlisting> + </para> + <para>Pushbuttons are enabled by invoking <emphasis role="italic">enableControl</emphasis> + on the dialog, the parameter being the control's symbolic ID + as shown in the first statement below. The second statement below puts focus on the + push-button - in this case by invoking the <emphasis role="italic">state</emphasis> + method of the control object. Finally, the cursor is placed in the Customer Name edit + control by invoking the dialog's <emphasis role="italic">focusControl</emphasis> method. + <programlisting> + <![CDATA[ self~enableControl("IDC_CUST_BTN_RECORDCHANGES") custControls[btnRecordChanges]~state = "FOCUS" -- Put focus on the button self~focusControl("IDC_CUST_EDT_CUSTNAME") -- place cursor in the CustName edit control. ]]> - </programlisting>The dialog is now in a state whereby the user can make changes to the - data. When the user presses the "Record Changes" button, the <emphasis role="italic" - >recordChanges</emphasis> method is invoked. Processing from this point is almost all - plain ooRexx with little ooDialog involvement: <itemizedlist> - <listitem> - <para>The method <emphasis role="italic">xformView2App</emphasis> (transform view - format to application format) is invoked and returns the data from the edit - controls as a directory, with the address element being an array. To read data - that the user has entered, the method uses the <emphasis role="italic" - >getText</emphasis> and <emphasis role="italic">getLine</emphasis> methods of - the Edit Control. </para> - </listitem> - <listitem> - <para>Then the <emphasis role="italic">checkForChanges</emphasis> method is invoked - with, as a parameter, the data returned from the <emphasis role="italic" - >xformView2App</emphasis> method.</para> - </listitem> - <listitem> - <para>If the data has not changed, a message box is displayed. If it has changed, - then the old data is replaced with the new. In either case, the edit controls are - set to read-only, and the "Record Changes" button is disabled.</para> - </listitem> - </itemizedlist></para> -<para>The next chapter discusses the use of the ooDialog class - <computeroutput>ResDialog</computeroutput>, which uses a compiled resource file (a *dll file) - instead of the *.rc file that <computeroutput>RcDialog</computeroutput> requires. + </programlisting> + The dialog is now in a state whereby the user can make changes to the + data. When the user presses the "Record Changes" button, the + <emphasis role="italic">recordChanges</emphasis> method is invoked. + Processing from this point is almost all + plain ooRexx with little ooDialog involvement: + <itemizedlist> + <listitem><para>The method <emphasis role="italic">xformView2App</emphasis> + (transform view format to application format) is invoked and returns the data from the edit + controls as a directory, with the address element being an array. To read data + that the user has entered, the method uses the <emphasis role="italic">getText</emphasis> + and <emphasis role="italic">getLine</emphasis> methods of the Edit Control.</para> + </listitem> + <listitem><para>Then the <emphasis role="italic">checkForChanges</emphasis> method is invoked + with, as a parameter, the data returned from the + <emphasis role="italic">xformView2App</emphasis> method.</para> + </listitem> + <listitem><para>If the data has not changed, a message box is displayed. If it has changed, + then the old data is replaced with the new. In either case, the edit controls are + set to read-only, and the "Record Changes" button is disabled.</para> + </listitem> + </itemizedlist> + </para> +<para>Suppose in the middle of updating, the user presses the Escape key by mistake? Try it. + The dialog disappears - together with any changes made. This is + certainly not best practice, and is addressed in the next chapter which discusses the use + of ooDialog's <computeroutput>ResDialog</computeroutput> class. A dialog + subclassed from <computeroutput>ResDialog</computeroutput> uses a compiled + resource file (a *dll file) instead of the *.rc file + required by an <computeroutput>RcDialog</computeroutput> subclass. </para> </section> <!--end of section 4.3.3.2 --> Modified: docs/trunk/oodguide/Chapter05.xml =================================================================== --- docs/trunk/oodguide/Chapter05.xml 2012-01-25 12:21:52 UTC (rev 7455) +++ docs/trunk/oodguide/Chapter05.xml 2012-01-26 11:15:42 UTC (rev 7456) @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter05 - Using Binary Resource Dialogs v00-06 29Nov11 +<!-- Chapter05 - Using Binary Resource Dialogs v00-07 25Jan12 5.1 - Dialog Initiation - using the newInstance class method. 5.2 - Compiling a binary resource file 5.3 - Differences between RcDialog and ResDialog @@ -53,6 +53,7 @@ v00-05 17Aug11: Updated to reflect change to using .application~setdefaults. v00-06 29Nov11: Updated to discuss disabling close (or doing something to over-ride normal Windows behaviour). + v00-07 25Jan12: Minor corrections to wording after proof-read. --> <chapter id="chapFive"> <title>Using Binary Resource Dialogs</title> @@ -556,7 +557,7 @@ beginning and start again. </para> </section> <!-- End of section 5.4.5 --> -<section><title>Controlling Dialog Cancel</title> <!-- Section 5.4.6 --> +<section id="chap05-dlgCancel"><title>Controlling Dialog Cancel</title> <!-- Section 5.4.6 --> <para>Windows provides for three ways for the user to cancel a dialog: by pressing the Esc key, by clicking on the "close" icon at the extreme top right of the dialog, or by clicking the "close" action on the system menu (click the icon at the extreme top left of the window). This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-01-26 13:58:14
|
Revision: 7458 http://oorexx.svn.sourceforge.net/oorexx/?rev=7458&view=rev Author: osims Date: 2012-01-26 13:58:05 +0000 (Thu, 26 Jan 2012) Log Message: ----------- Minor mod to Chap04, correct copyright on app04. Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/appendix04.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-01-26 11:16:32 UTC (rev 7457) +++ docs/trunk/oodguide/Chapter04.xml 2012-01-26 13:58:05 UTC (rev 7458) @@ -684,7 +684,9 @@ </para> <para>Suppose in the middle of updating, the user presses the Escape key by mistake? Try it. The dialog disappears - together with any changes made. This is - certainly not best practice, and is addressed in the next chapter which discusses the use + certainly not best practice, and is addressed in the next chapter + (see <link linkend="chap05-cancel" endterm="chap05-cancel.title"></link>) + which discusses the use of ooDialog's <computeroutput>ResDialog</computeroutput> class. A dialog subclassed from <computeroutput>ResDialog</computeroutput> uses a compiled resource file (a *dll file) instead of the *.rc file Modified: docs/trunk/oodguide/appendix04.xml =================================================================== --- docs/trunk/oodguide/appendix04.xml 2012-01-26 11:16:32 UTC (rev 7457) +++ docs/trunk/oodguide/appendix04.xml 2012-01-26 13:58:05 UTC (rev 7458) @@ -2,7 +2,7 @@ # # Description: Open Object Rexx: ooDialog User Guide XML file. # - # Copyright (c) 2011-2011, Rexx Language Association. All rights reserved. + # Copyright (c) 2011-2012, 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 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-01-26 20:43:09
|
Revision: 7459 http://oorexx.svn.sourceforge.net/oorexx/?rev=7459&view=rev Author: osims Date: 2012-01-26 20:43:02 +0000 (Thu, 26 Jan 2012) Log Message: ----------- Minor changes to Chap04 and Chap05 after proof-reading. Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/Chapter05.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-01-26 13:58:05 UTC (rev 7458) +++ docs/trunk/oodguide/Chapter04.xml 2012-01-26 20:43:02 UTC (rev 7459) @@ -628,7 +628,8 @@ </para></listitem> <listitem><para>Second, the Customer Address data is an array, which for display in a multi-line edit control must be transformed into a text string with line-ends - inserted at appropriate places. This kind of transformation is very usual + inserted at appropriate places. This is done in the <emphasis role='italic'>showData</emphasis> + method. Data transformation of this sort is very usual within view classes; after all, it's the responsibility of any View class (or of its subsidiary classes or routines) to handle any re-formatting for display purposes. </para></listitem> @@ -666,18 +667,17 @@ Processing from this point is almost all plain ooRexx with little ooDialog involvement: <itemizedlist> - <listitem><para>The method <emphasis role="italic">xformView2App</emphasis> - (transform view format to application format) is invoked and returns the data from the edit - controls as a directory, with the address element being an array. To read data - that the user has entered, the method uses the <emphasis role="italic">getText</emphasis> - and <emphasis role="italic">getLine</emphasis> methods of the Edit Control.</para> + <listitem><para>The <emphasis role="italic">recordChanges</emphasis> method reads data from + dialog controls using the <emphasis role="italic">getText</emphasis> + and <emphasis role="italic">getLine</emphasis> methods of the Edit Control. + Any view-formatted data is transformed into application format (in this case, the Address + needs to be transformed from strings with line-end characters to an array).</para> </listitem> <listitem><para>Then the <emphasis role="italic">checkForChanges</emphasis> method is invoked - with, as a parameter, the data returned from the - <emphasis role="italic">xformView2App</emphasis> method.</para> + with, as a parameter, the data just read in from the dialog controls.</para> </listitem> <listitem><para>If the data has not changed, a message box is displayed. If it has changed, - then the old data is replaced with the new. In either case, the edit controls are + then the old data is replaced with the new. Finally, in either case, the edit controls are set to read-only, and the "Record Changes" button is disabled.</para> </listitem> </itemizedlist> Modified: docs/trunk/oodguide/Chapter05.xml =================================================================== --- docs/trunk/oodguide/Chapter05.xml 2012-01-26 13:58:05 UTC (rev 7458) +++ docs/trunk/oodguide/Chapter05.xml 2012-01-26 20:43:02 UTC (rev 7459) @@ -2,7 +2,7 @@ # # Description: Open Object Rexx: ooDialog User Guide XML file. # - # Copyright (c) 2011-2012 Rexx Language Association. All rights reserved. + # Copyright (c) 2011-2012, 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 @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter05 - Using Binary Resource Dialogs v00-07 25Jan12 +<!-- Chapter05 - Using Binary Resource Dialogs v00-07 26Jan12 5.1 - Dialog Initiation - using the newInstance class method. 5.2 - Compiling a binary resource file 5.3 - Differences between RcDialog and ResDialog @@ -53,7 +53,7 @@ v00-05 17Aug11: Updated to reflect change to using .application~setdefaults. v00-06 29Nov11: Updated to discuss disabling close (or doing something to over-ride normal Windows behaviour). - v00-07 25Jan12: Minor corrections to wording after proof-read. + v00-07 26Jan12: Various minor updates to wording. --> <chapter id="chapFive"> <title>Using Binary Resource Dialogs</title> @@ -84,8 +84,8 @@ ooRexx routine, for dialog initiation. By "initiation" is meant the two statements "<computeroutput>dlg=.[DialogClassName]~new</computeroutput>" and "<computeroutput>dlg~execute(...)</computeroutput>". In other words, the responsibility - for issuing these two initiation statements - which handle the technical creation and - initial display of the dialog - have been outside the dialog class. If they could be moved + for issuing these two initiation statements - which are essential for the creation of the + dialog - have previously been outside the dialog class. If they could be moved <emphasis role="italic">within</emphasis> the class, then encapsulation would be enhanced - always a desirable thing. The question is, how. Well, ooRexx has a mature implementation of OO that (among other things) allows for class methods (as opposed to instance methods). @@ -111,7 +111,8 @@ <primary>Class methods</primary> <secondary>newInstance</secondary> </indexterm> Note also that the first parameter of the - <computeroutput>.ProductView~new()</computeroutput> statement allows file paths. </para> + <computeroutput>.ProductView~new()</computeroutput> statement allows for file paths + to be specified.</para> </section> <!-- End of section 5.1 --> <section id="chap05-resfile"> @@ -175,9 +176,8 @@ D:\...\Exercise04>startup D:\...\Exercise05>startup StartCustomerView Routine-01: Start. .ProductView-newInstance-01: Start. CustomerView-init-01. ProductView-init-01. -CustomerView-initAutoDetection-01. ProductView-initAutoDetection-01. CustomerView-createMenuBar-01. -StartCustomerView Routine-02: dlg~activate. ProductView-newInstance-02: dlg~Activate. +StartCustomerView Routine-02: dlg~activate. .ProductView-newInstance-02: dlg~Activate. CustomerView-activate-01. ProductView-activate-01. CustomerView-initDialog-01. ProductView-initDialog-01 ]]> @@ -198,6 +198,9 @@ as bitmaps and/or icons, the number of files required for an RcDialog class can result in a minor file management challenge in the runtime environment. A ResDialog class, on the other hand, has only two files: the *.dll and the *.h. </para> + <para>See <link linkend="apx-dlgsequences" endterm="dlgsequences.title"></link> for a + comparison of dialog startup methods comparing an <computeroutpur>RcDialog</computeroutpur>, + a <computeroutpur>ResDialog</computeroutpur> and a <computeroutpur>UserDialog</computeroutpur>.</para> </section> <!-- End of section 5.2.2 --> </section> @@ -219,9 +222,9 @@ <secondary>RadioButton</secondary> </indexterm> <para> For Radio Buttons to operate automatically - that is, when an "off" button is - clicked, the "on" button goes off - they must be within a Group Box. This is defined in + clicked, the previously "on" button goes off - they must be within a Group Box. This is defined in the *.rc file first as a GROUPBOX control with the style WS_GROUP. After this is defined, - the radio buttons, which must have the AUTORADIOBUTTON style, are placed in the groupbox. + the radio buttons (which must have the AUTORADIOBUTTON style) are placed in the groupbox. However, the containment is done through the order of controls in the *.rc file. To achieve this using ResEdit, first drag a Group Box control onto the dialog, and set the "Group" property to "True". Then drag the radio buttons from the controls palette into the @@ -275,7 +278,7 @@ grouped in the directory object <emphasis role="italic">prodControls</emphasis> for ease of "exposing" them across methods; also, edit control instances have the prefix "ec" in conformance with the - <link linkend="chap04-convs-names">naming standards</link> mentioned in Chapter 4. + <link linkend="chap04-convs-names">naming conventions</link> mentioned in Chapter 4. </para> </listitem> <listitem> @@ -299,7 +302,7 @@ </programlisting> The sixth argument to the event handler is the control object where the character event occurred, and the event must be forwarded to that object - that is, to the eventful edit control. The event is then handled by the mixin class, - where the numeric-only editing is done. Note that other method names can be used.</para> + where the numeric-only editing is done.</para> </listitem> </orderedlist> </para> @@ -308,13 +311,15 @@ <section id="chap05-accels"> <title>Menu Accelerators</title> <!-- Section 5.3.3 --> + <indexterm><primary>Menus</primary><secondary>Accelerator key</secondary></indexterm> + <indexterm><primary>Accelerator key</primary><secondary>in menus</secondary></indexterm> <para>Open the Product View dialog, and then press the Alt key on the keyboard, followed by the down-arrow key. The "Actions" menu is first highlighted and then opened. The top menu item is "Update Product" - with an underscore beneath the "U". Pressing the "U" key will then initiate the Update Product behavior. The underlined letter is known as an "accelerator" key. It is produced by placing an ampersand - (&) immediately before the letter that's to be the accelerator key. In the - <computeroutput>ProductView.rc</computeroutput> file, you'll see the Update menu item + (&) immediately before the letter that's to be the accelerator key on the *.rc file. + In <computeroutput>ProductView.rc</computeroutput>, you'll see the Update menu item defined as <computeroutput>MENUITEM "&Update Product", IDM_PROD_UPDATE</computeroutput>. </para> <para>Interestingly, if you mouse-click on the "Actions" menu to open it, the "U" is not @@ -336,6 +341,8 @@ <section id="chap05-imagecontrol"> <title>Creating the Image</title> <!-- section 5.3.4.1 --> + <indexterm><primary>Image</primary><secondary>creating</secondary></indexterm> + <indexterm><primary>Creating an Image</primary></indexterm> <para>An image is created by placing a bitmap (a file of type "*.bmp") into a "Picture Control". The bitmap and Picture control are both defined in the *.rc file, but placing the image into the picture control is done in code. </para> @@ -375,7 +382,7 @@ authoritative list of styles is found in the <ulink url="http://msdn.microsoft.com/en-us/library/bb773169%28v=VS.85%29.aspx"> <citetitle>Microsoft Control Library</citetitle></ulink>. Look up the Static - Control, and you'll find some thirty different styles. <indexterm> + Control, and you'll find around thirty different styles. <indexterm> <primary>Controls</primary> <secondary>Styles</secondary> </indexterm> @@ -414,7 +421,7 @@ 26.4). The second statement uses the ResourceImages's <emphasis role="italic" >getImage</emphasis> method (see ooDialog Reference 26.2.4) to return an instance of the <computeroutput>Image</computeroutput> class. The last statement creates a static - control and sets the image in it. </para> + control proxy and sets the image in it. </para> </section> <!-- end of section 5.3.4.1.2 --> </section> @@ -441,7 +448,7 @@ closed (see ooDialog Reference 3.8.5). Its purpose is to allow for clean-up. In the case of the About dialog, the two resources used (an image and a font) are let go. This is not really necessary in this simple application, but is a good habit to get into (see - the discussion at the end of section 26.2 of the ooDialog reference).</para> + the discussion at the start of section 26.2 of the ooDialog reference).</para> </section> <!-- End of section 5.3.4.2 --> </section> @@ -458,7 +465,7 @@ <section><title>Data Types</title> <!-- Section 5.4.1 --> <para>Most non-trivial software systems consist of a number of components. Each of these could in principle be written in a different programming language - assuming of course that all - the languages support common invocation mechanisms. Within each component there are typically some number of + the languages are supported by common invocation mechanisms. Within each component there are typically some number of classes, and these interact privately. Between components, which often interact with "data-heavy" invocations, it is usual to define specific "data-only" classes, so that everyone can be sure of using the same data structures. Examples are: a Customer data class, an Address data class, and a SalesOrder data class. @@ -477,13 +484,13 @@ <section><title>View Data vs Application data</title> <!-- Section 5.4.2 --> <para>There is often a difference between data that the user sees or enters on a dialog and the data - that flows between components in data types. This is similar to the difference between - data in a normalized database and data as used by application code. For example, on the + that flows between components in data types (just as there are differences between + data in a normalized database and data as used by application code). For example, on the Product View dialog, a price is shown with two decimal digits after a decimal point. Price in the <computeroutput>ProductDT</computeroutput> data type, on the other hand, has no decimal places - it's expressed in units of 1/100s of the currency unit (that is, in cents if the currency unit is - the Dollar). Thus the price from the data type must be transformed somewhere for both display and - user input purposes</para> + the Dollar). Thus the price data type must be transformed both when displayed to the + user and when read in by the program.</para> <para>The principle for where to do the transformation is simple: do it as close to the screen as possible (just as, at the other end, transformation to database formats are done as close to the DB programming interface (e.g. SQL) as possible, meaning that most of the @@ -514,7 +521,7 @@ <emphasis role="italic">about</emphasis> method is modal. That is, the Product View window cannot be accessed while the About window is open. This is because "About" was launched using the <emphasis role='italic'>execute(..)</emphasis> method. Making an "about - box" modal seems quite reasonable. But in later chapters some of ooDialog's alternatives to + box" modal seems quite reasonable. But in later chapters alternatives to <emphasis role='italic'>execute</emphasis> will be used in order to launch non-modal dialogs. </para> </section> <!-- End of section 5.4.3 --> @@ -557,7 +564,7 @@ beginning and start again. </para> </section> <!-- End of section 5.4.5 --> -<section id="chap05-dlgCancel"><title>Controlling Dialog Cancel</title> <!-- Section 5.4.6 --> +<section id="chap05-cancel"><title id="chap05-cancel.title">Controlling Dialog Cancel</title> <!-- Section 5.4.6 --> <para>Windows provides for three ways for the user to cancel a dialog: by pressing the Esc key, by clicking on the "close" icon at the extreme top right of the dialog, or by clicking the "close" action on the system menu (click the icon at the extreme top left of the window). @@ -602,8 +609,7 @@ <listitem> <para>The third state is the modal "exit messagebox" state which, depending on the user's choice, either closes the dialog or returns to the "inUpdate" state. - If the user selects any of the close actions, then the dialog closes - immediately. </para> + If the user selects "close", then the dialog closes immediately. </para> </listitem> </orderedlist> </para> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-02-03 15:48:04
|
Revision: 7467 http://oorexx.svn.sourceforge.net/oorexx/?rev=7467&view=rev Author: osims Date: 2012-02-03 15:47:52 +0000 (Fri, 03 Feb 2012) Log Message: ----------- Added Paths: ----------- docs/trunk/oodguide/Chapter06.xml Removed Paths: ------------- docs/trunk/oodguide/Chapter06.xml Property Changed: ---------------- docs/trunk/oodguide/ Property changes on: docs/trunk/oodguide ___________________________________________________________________ Modified: svn:ignore - Chapter04-image1 (old).jpg Thumbs.db chapter06.xml + Chapter04-image1 (old).jpg Chapter06 v00-03.xml Thumbs.db chapter06.xml Deleted: docs/trunk/oodguide/Chapter06.xml =================================================================== --- docs/trunk/oodguide/Chapter06.xml 2012-02-03 15:37:58 UTC (rev 7466) +++ docs/trunk/oodguide/Chapter06.xml 2012-02-03 15:47:52 UTC (rev 7467) @@ -1,486 +0,0 @@ -<!--######################################################################### - # - # Description: Open Object Rexx: ooDialog User Guide XML file. - # - # Copyright (c) 2011-2012, 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. - # - ######################################################################### ---> - -<!-- Chapter06 - List Views, Re-Sizing, and PopUps v00-03 03Feb12 - - Changes: - v00-01 25Aug11: First version - v00-02 03Dec11: Second version. - v00-03 03Feb12: Sorted out structure and added some text. - - - 6. An Application Workplace - -- the OrderManagerView - is the "home" window. It'll have a sign-on and password field in a sub-dialog - (also programmer-designed) which comes modally when the OrderManagemwent - window is established. Thus we demonstrate/discuss: - - programmatic layout (can only use userDialog) - - modal sub-window - - Handling icons and showing them. - - password dialog (shows asterisks when you type into it) - but can avoid - with startup param "skipPW" (but the dialog in the startup prog to show - use of ooDialog in normal rexx progs). - - Icons that when dbl-clicked startup other views - - Most menu items on OrderMgmgt dialog not implemented. - - - app function very absent - e.g. all dialog data is hard-coded - same for Cust, Prod, Order - no real data in any file. - - e.g. no function for "New Order" - 6.1 Program Structure - 6.1.1 Have to change .rc file manually to get icon showing properly - ResEdit makes it .\bmp\icon.ico - instead of .\order\bmp\icon.ico - even if you start resedit from Exercise06 and specify "resedit order\orderlistview.rc". - (Paths - esepc for ResEdit.) - 6.1.2 about use of .Application - not good for a shipped app - address later when "package" an app for shipping. - 6.1.3 Mention HRS class name changes to allow for possible packaging - all classes in a single file. - 6.1.3 Stand-alone testing - - incl how get dlgicons to show (Answer: rc file must be built and saved into the parent folder so that file path is right for invocation from the parent folder. ) - Ditto for ResDialog - compile the dll in the parent folder (check this!) - 6.1.4 Several place-holders for app functions - custmodel & custdata created for each showmodel. Fix in next exercise. - 6.1.5 One Folder per component - for resources such as bitmaps/icons for RcDialogs, need to run resedit from parent folder so that path to resource is correct when run the component from the parent folder. - 6.1.6 Reference to standalone code and the sample. Also must start from the Exercise06 folder - Customer\StartupCustomer - 'cos all paths in the code are relative to the Exercise06 folder. - 6.1.7 Why no Model/Data components for list views? - 6.1.8 Generally, in real life, creating something (Customer, Product, Order) requires a process different from merely updating something. This means a different GUI. But for this Guide, we'll assume Customer and Product get new records from a different place, - so new records can(in this sample app) be got by adding to the relevant data files. However, OrderForm and Order are different - so have a component each. - 6.1.9 The lists create a new instance for each list item - which is silly. - 6.1.10 Naming - explain diff between OrderMgmt & OrderMgr where appropriate. - -??? Mention standalone execution - point to sample code in samples and to App3. - - 6.2 Pop-Ups and Parents incl Non-Modal Dialogs - 6.2.1 How get pop-up to pop up away from parent? Answer - have to code it yourself. - 6.2.2 Starting a dialog from a dialog (incl interpret statement - pointer to later) - Use of "interpret", better would be to have a class object - but later we'll need interpret (won't we?) for the ObjectMgr. - Leave “interpret” in but mention it – say class object would be better - show how can be fixed in later exercise – where - this will be moved to a support class (ObjectMgr). - - 6.3 Icons and Lists - 6.3.1 The Icon View - - List Views - normal icon view - a "workplace" for Order Management.. - - Auto-resizing when window sized by user - - 6.3.2. The Report View - - Looking at the two list views, almost begs for a superclass. - - how do different fonts for the listView items - - Explain the surfacing of an instance in the listview dialogs - check the showModel method. - - 6.4 Re-Sizing Dialogs - - 6.5 Creating and Using Icons - - Icons - making them, getting 'em into the program. - - (1) Does the icon have to be a certain size, or will it get automatically shrunk? - (2) If it has to be a certain size, what's the size, and are there any restrictions as to the palette (I'm no expert, but using GIMP I'm given the option of saving as 16-bit, 24-bit or 32-bit color (or I think it's color!)). - (3) In the ~execute statement, I need to provide an ID. Does this mean I must have a *.rc file? Or can I invent an ID programmatically somehow - perhaps along the same lines as creating an ImageList? - (4) I want to assign my own icon as the dialog icon (that is, the icon at the extreme top left of a dialog). This is done (I understand) in the ~execute(..., <icon_ID> ) method (ooDialog Reference section 3.10.3). - - 6.6 Utility Dialogs - <- ??? <What's this??> (Is this the layer - process-entity-utility? Or just useful "canned" dialogs?) - - Mention password on startup to illustrate ooDialog use in otherwise non-ooDialog rexx programs. - "startup enterPW" - password is "Password". - - - - - ---> -<chapter id="chapSix"><title>An Application Workplace</title> -<indexterm><primary>OrderManager component</primary></indexterm> -<para>This chapter introduces the Order Management application, which is designed as a "workplace" - for a user handling sales orders. As such, it provides access to the required components - - customers, products, orders, and order forms. A common approach for a "workplace" dialog is to - provide an icon for each component that the user may wish to use. In the - <computeroutput>Exercise06</computeroutput> folder, run - <computeroutput>startup.rex</computeroutput>. The Order Management dialog opens, and - consists mainly of a List View containing four icons. Move the icons around; double-click them - and if a Customer, Product, or Order List appears then double-click a list item; re-size the - Order Management window; check out the menu items and the pushbuttons. As you see, while much - of the application function is absent, and the data is hard-coded, the essential parts of the - Order Management application mentioned in <xref linkend="chapFour"/> are visible. This chapter - addresses the following topics in the context of the Order Management application: <itemizedlist> - <listitem> - <para><xref linkend="chap06-struc"/></para> - </listitem> - <listitem> - <para><xref linkend="chap06-listviews"/>Icons and Lists</para> - </listitem> - <listitem> - <para><xref linkend="chap06-popups"/></para> - </listitem> - <listitem> - <para><xref linkend="chap06-resize"/></para> - </listitem> - <listitem> - <para><xref linkend="chap06-icons"/></para> - </listitem> - <listitem> - <para><xref linkend="chap06-utildlgs"/>Utility Dialogs</para> - </listitem> - </itemizedlist> - </para> - -<section id="chap06-struc"><title>Program Structure</title> <!-- Section 6.1 --> - <para>In Exercise06, each business component has its own folder: - Customer, Order, OrderMgr, and Product. Customer and Product are more or less identical - to the same components introduced in Exercises 04 and 05. - Placing each business component into a separate folder - helps promote high cohesion and low coupling in the software, - since the internals of each business component are opaque to other business components. - Thus another application (e.g. Customer Relationship - Management) might be able to make use of the Customer business component without change. - The Order Management business component is unlikely to be re-used in other applications as it is - a kind of "process" business component that "choreographs" the other business components. - To the user, creating a new sales order consists of "choreographing" the various business aspects - required - creating an Order Form (used to assemble the customer order), searching for and selecting a - specific Customer, searching for and selecting one or more Products, recording the quantities ordered, - and producing a Sales Order that is the "contract" between supplier and customer. Of course, the OrderManagement - component could be used by "higher-level" components such as business processes or workflows. In systems - organized according to these principles, invocation of components takes the form of a directed acyclic graph. - </para> - <para> - Within each business component are one or more component groups and components. For example, the Customer - business component contains two component groups: CustomerList and Customer. In turn, - each of these consists of one View component and one Model component. Both model components - share a single Data component. The Customer and Product - component groups are essentially identical to those introduced in Exercises 4 and 5 respectively. - </para> - <para> - The Order Management business component is, in this Exercise, implemented by a view class only. In fact, - there are two view classes, each in its own .rex file: <computeroutput>OrderMgmtBaseView</computeroutput> - and its subclass <computeroutput>OrderMgmtView</computeroutput>. - <computeroutput>OrderMgmtBaseView</computeroutput> - contains the code for handling a re-sizable dialog, and is a subclass of <computeroutput>UserDialog</computeroutput> - which is required for any dialog that is dynamically - re-sizable (see <xref linkend="chap06-resize"/>). <computeroutput>OrderMgmtView</computeroutput> contains the code - specific to the Order Management application. - The only reason for splitting the code like this is that it seems to fall happily into these two parts. This reduces - the amount of code in any one class or file, and so makes for better readability. - </para> - <para> - Note that the "data" of the OrderManagement business component is the set of icons and their associated data. - In Exercise06, this data is effectively embedded in the View classes. However, the code in the - <computeroutput>OrderMgmtView</computeroutput> class uses an <emphasis role="italic">interpret</emphasis> - instruction to launch views of the components represented by icons. Thus in principle, additional components - can be added without changing the code in the <computeroutput>OrdermgmtView</computeroutput> class. To support this, - a separate file - <computeroutput>RequiresList.rex</computeroutput> - contains the set of - <emphasis role="italic">::requires</emphasis> statements corresponding to the components that might be surfaced. - This is why the first executable statement in the file <computeroutput>OrderMgmtView.rex</computeroutput> is - <emphasis role="italic">call "OrderMgmt\RequiresList.rex"</emphasis>. Examples of possible additional components - could be a "commodities" component which shows - the commodities required to produce a given product; or a credit-check component that links to an external - credit-check agency. - </para> -</section> <!-- End of section 6.1 --> - - -<section id="chap06-listviews"><title>Icons and Lists</title> <!-- Section 6.2 --> - <indexterm><primary>ListView</primary></indexterm> - <indexterm><primary>Controls</primary><secondary>ListView</secondary></indexterm> - <indexterm><primary>Icons</primary><secondary>in a ListView</secondary></indexterm> - <para>The <computeroutput>ListView</computeroutput> should not be confused with <computeroutput>ListBox</computeroutput>; - a ListView (see ooDialog Reference chapter 20) is a souped-up ListBox with lots of additional features. In particular: - <itemizedlist> - <listitem><para>An item in a ListView can be a complex structure or "record" containing - multiple fields. One of these fields is termed the "label" of the item.</para></listitem> - <listitem><para>ListView items can be displayed in four different modes: - <itemizedlist> - <listitem><para>Icon view - each item appears as a full-sized icon with a label below it. - Items can be dragged around the ListView.</para></listitem> - <listitem><para>Small-icon view - each item appears as a small icon with a label to its right. - Items can be dragged around the ListView.</para></listitem> - <listitem><para>List view - each item appears as a label with an optional small icon to its left.</para></listitem> - <listitem><para>Report view - each item appears as a row in a table with an optional small icon to its left. - </para></listitem> - </itemizedlist> - The four different modes are well illustrated by the sample program <computeroutput>oodListViews.rex</computeroutput> - located in the <computeroutput>ooRexx\samples\oodialog</computeroutput> folder.</para></listitem> - </itemizedlist> - </para> - <para>In the Order Management application, the ListView control provides the main area of the Order Management dialog - where draggable icons (icon view) represent the various components of the application. - It also provides the tabular lists (report views) in the CustomerList, ProductList, and OrderList dialogs. - </para> - - <section id="chap06-listview-icon"><title>The Icon View</title> <!-- Section 6.2.1 --> - <para> - -<!-- - OMBV -1 ::attribute lv - - OMV -2 ::method init - expose records - self~createIconList 3 - records = self~initRecords 4 - -5 ::method initDialog - expose iconList records - self~lv~newListView(..) - self~lv~setImageList(..) - /*- Add icons (i.e. records) to the ListView: (actually used two hyphens at start - but oXygen doesn't like this.)*/ - do i=1 to records~items - self~lv~addRow(, i-1, records[i]~name) - end - -3 ::method createIconList - expose iconList - imgCustList = .Image~getImage( filename ) - ... - iconList = .ImageList~create(...) - iconList~add(imgCustList) /* item 0 in the list */ - ... - -4 ::method initRecords - expose records - records = .array~new() - rec = .directory~new - rec~ID = "CustomerList" - rec~name = "Customer List" - records[1] = rec - ... - return records - -6 ::method onDoubleClick - expose records - index = self~lv~focused /* lv is an attribute of OBMBV */ ---> - - The OrderManagement dialog uses the Icon View option of the ListView control. Five things are needed to produce an - icon view: first, create (or obtain) some icons; second, specify the <computeroutput>ICON</computeroutput> style for the ListView - control; third, create an ImageList from the icons (required by the ListView control); fourth, create a set of records - (one record per icon) to be loaded into the ListView; and fifth, load the icons and records into the ListView. - </para> - <orderedlist numeration="arabic"> - - <listitem> <!-- One --> - <para><emphasis role="bold"><emphasis role="italic">Produce the Icons</emphasis></emphasis></para> - <para>First, the large "icons" in the ListView are actually bitmaps. Icons and bitmaps have different formats, and different uses, - and there are a number of differences between them. The icons themselves - are in the folders of the relevant business components, so the icon for the Customer List, for example, is - <computeroutput>Exercise06\Customer\bmp\CustList.bmp</computeroutput>. (The <computeroutput>*.ico</computeroutput> - files are the dialog icons.) - A number of tools are available for creating and editing images, icons, bitmaps etc., - some of them providing conversion and re-sizing capabilities. One such is GIMP (GNU Image Manipulation Program) from - http://www.gimp.org. - <indexterm><primary>Bitmap Editor</primary></indexterm><indexterm><primary>Icon editor</primary></indexterm> - </para> - </listitem> - - <listitem> <!-- Two --> - <para><emphasis role="bold"><emphasis role="italic">Specify the ICON Style</emphasis></emphasis></para> - <para>The icon style for a ListView control is specified either in the - <computeroutput>*.rc</computeroutput> file as the - <computeroutput>LVS_ICON</computeroutput> (in ResEdit, set the "View" property to - "Icon"), or in a UserDialog, by creating the ListView control in the - <emphasis role="italic">initDialog</emphasis> method using the - <computeroutput>ICON</computeroutput> style (e.g.: - <computeroutput>self~createListView(IDC_ORDMGMT_ICONS, ... "ICON")</computeroutput> - where the first parameter is the ID for the ListView control.). </para> - </listitem> - - <listitem> <!-- 3 --> - <para><emphasis role="bold"><emphasis role="italic">Create an ImageList</emphasis></emphasis></para> - <para>The ListView documentation provides several ways to load icons. Probably the easiest is to create an - object of type <computeroutput>ImageList</computeroutput> (see ooDialog Reference - section 26.3) which is loaded into the ListView. In <computeroutput>OrderMgmtView</computeroutput>, this - is done in the <emphasis role="italic">createIconList</emphasis> method - (invoked from the <emphasis role="italic">init</emphasis> method) as follows: - <programlisting> - <![CDATA[ - ::METHOD createIconList PRIVATE - expose iconList - imgCustList = .Image~getImage("customer\bmp\CustList.bmp") - imgProdList = .Image~getImage("product\res\ProdList.bmp") - imgOrderList = .Image~getImage("order\bmp\OrderList.bmp") - imgOrderForm = .Image~getImage("order\bmp\OrderForm.bmp") - -- Boldly assume no errors in creating the Image List or in the ~getImage statements. - iconList = .ImageList~create(.Size~new(64, 64), .Image~toID(ILC_COLOR4), 4, 0) - iconList~add(imgCustList) -- item 0 in the list - iconList~add(imgProdList) -- item 1 in the list - iconList~add(imgOrderList) -- item 2 in the list - iconList~add(imgOrderForm) -- item 3 in the list - imgCustList~release - imgProdList~release - imgOrderList~release - imgOrderForm~release - return - ]]> - </programlisting> - For each icon, only two statements are required: create an Image from file then copy it to the ImageList (and a third, if you're - a polite programmer and try to clean up afterwards, release the image). - </para> - </listitem> - - <listitem> <!-- 4 --> - <para><emphasis role="bold"></emphasis>Create Records</para> - <para>Records are typically created in the <emphasis role="italic">init</emphasis> method (or in a method invoked from there). - In <computeroutput>OrderMgmgtView</computeroutput> the records are created in the <emphasis role="italic">initRecords</emphasis>) - method which is invoked from <emphasis role="italic">init</emphasis>. Each record has two fields: the text to appear beneath - the icon, and the class name of the dialog to be surfaced when a user double-clicks on an icon. The design choice for these records - is that each record will be a directory, and each directory will stored in an array. The array index of a record is equivalent - to the position of its icon in the ImageList (remembering that arrays are 1-based while ImageLists are 0-based). The code for loading - the record array is - as follows (showing only the Sales Orders item for brevity): - <programlisting> - <![CDATA[ - ::METHOD initRecords PRIVATE - expose records - records = .array~new() - ... - rec = .directory~new - rec~ID = "OrderList" - rec~name = "Sales Orders" - records[3] = rec - ... - return records - ]]> - </programlisting> - </para> - </listitem> - <listitem> <!-- 5 --> - <para><emphasis role="bold">Load the ImageList and the Records</emphasis></para> - <para>Loading icon images and records into the ListView is done in the - <emphasis role="italic">initDialog</emphasis>method: - <programlisting><![CDATA[ - ::METHOD initDialog - expose records iconList - self~initDialog:super - self~lv~setImageList(iconList, .Image~toID(LVSIL_NORMAL)) - do i=1 to records~items - self~lv~addRow(, i-1, records[i]~name) - end - ]]> - </programlisting> - After invoking the superclass, the icons in the ImageList are applied to the ListView control - using its <emphasis role="italic">setImageList</emphasis> method. The second parameter of this method - specifies the size of the icons by invoking - the Image class' <emphasis role="italic">toID</emphasis> method with the parameter <emphasis role="italic">LVSIL_NORMAL</emphasis> - (the flag for the icon view). The Image class is used to work with and manipulate images, - and is described in section 26.2 of the ooDialog Reference. The variable - <emphasis role="italic">self~lv</emphasis> is the list view proxy, <emphasis role="italic">lv</emphasis> being an - attribute of the <computeroutput>OrderMgmtBaseView</computeroutput> superclass. - The icons having been set, the records are then added - using the ListView's <emphasis role="italic">addRow</emphasis> method. The first parameter is the index of the list item - - if omitted, the record is added after the last. The second parameter is the index of the icon to be used with this record, and - the last parameter is the label for the list item - the string "Customer List" in the case of the first item added to the ListView in - <computeroutput>OrderMgmtView</computeroutput>. - </para> - </listitem> - </orderedlist> - - </section> <!-- End of section 6.2.1 --> - - <section id="chap06-listview-report"><title>The Report View</title> <!-- Section 6.2.2 --> - <para>Three of the icons in the Order Management dialog surface a list when double-clicked - Customers, Products, and Orders. - These three components are technically very similar - to the extent that a "list superclass" could perhaps be created. - For the meantime, however, this is not done, and each list is quite separate. However, their similarity means that discussing one - list - the Customer List - effectively addresses all. - </para> - <para></para> - </section> <!-- End of section 6.2.2 --> - - -</section> <!-- End of section 6.2 --> - - <section id="chap06-popups"><title>Non-Modal Dialogs</title> <!-- Section 6.3 --> - <para> - </para> - </section> <!-- End of section 6.3 --> - -<section id="chap06-resize"><title>Re-sizing Dialogs</title> <!-- Section 6.4 --> -<para>If you haven't already done so, try re-sizing the Order Management dialog. - The ListView containing the icons - expands to match the new window size, and one of the two pushbuttons moves as well, although their size - - unlike the size of the List View - does not change. This re-sizing function is only available - for a <computeroutput>UserDialog</computeroutput>, and requires a number of methods and lines of code. - ooDialog provides three samples of the resizing function in the folder - <computeroutput>ooRexx\samples\oodialog</computeroutput> folder - - the relevant programs being <computeroutput>dlgAreaUDemo.rex</computeroutput>, - <computeroutput>dlgAreaUDemoTwo.rex</computeroutput>, and - <computeroutput>dlgAreaUDemoThree.rex</computeroutput>. - <computeroutput>OrderManagementBaseView.rex</computeroutput> includes much of the code from the last - of these three samples. -</para> -<para> - The re-sizing function is provided by two ooDialog classes: <computeroutput>dlgAreaU</computeroutput> - and <computeroutput>dlgArea</computeroutput> (see ooDialog Reference sections 10.14 and 10.15). - An important constraint is that, because <computeroutput>dlgAreaU</computeroutput> parses - the source code of the <emphasis role="italic">defineDialog</emphasis> method in order to handle re-sizing, - it will only work with <computeroutput>UserDialog</computeroutput>, where the dialog template is created - through explicit control creation statements. In addition, since the source code is required at run-time, - it will not work if the source code is tokenized using <emphasis role="italic">rexxc</emphasis>. -</para> -<para> - Essentially, the dialog is first split into a number of areas - two areas for the - OrderManagement dialog. ears for . dilaog defines the A re-sizeable dialog - an excellent sample dialog - - </para> -</section> <!-- End of section 6.4 --> - - -<section id="chap06-icons"><title>Creating and Using Icons</title> <!-- Section 6.5 --> - <para>- Icons - making them, getting 'em into the program. - GIMP (GNU Image Manipulation Program) from - http://www.gimp.org -</para> -</section> <!-- End of section 6.5 --> - -<section id="chap06-utildlgs"><title>Utility Dialogs</title> <!-- Section 6.6 --> - <indexterm><primary>Password dialog</primary></indexterm> - <indexterm><primary>Utility routine</primary><secondary>PasswordBox</secondary></indexterm> - <para>A subject not yet mentioned is the use of ooDialog utility classes and routines in non-ooDialog ooRexx programs. - These are documented in Chapter 9 of the ooDialog Reference. The routines are very simple, and are often one-liners. - As an example, the Exercise06 startup program - provides for entry of a password using the (one-line) PasswordBox routine. - Invoking <emphasis role="italic">startup enterPW</emphasis> produces a password box that will accept the password - "Password". If you get the password wrong, the startup routine will silently end. The code is as follows: - <programlisting> - <![CDATA[ - parse arg pwOption - if pwOption = "enterPW" then do - pwd = PasswordBox("Please enter your password","Sign In") - if pwd \= "Password" then exit - end - .OrderMgmtView~newInstance - ::REQUIRES "OrderMgmt\OrderMgmtView.rex" - ]]> - </programlisting> - - </para> -</section> <!-- End of section 6.6 --> - -</chapter> - Added: docs/trunk/oodguide/Chapter06.xml =================================================================== --- docs/trunk/oodguide/Chapter06.xml (rev 0) +++ docs/trunk/oodguide/Chapter06.xml 2012-02-03 15:47:52 UTC (rev 7467) @@ -0,0 +1,486 @@ +<!--######################################################################### + # + # Description: Open Object Rexx: ooDialog User Guide XML file. + # + # Copyright (c) 2011-2012, 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. + # + ######################################################################### +--> + +<!-- Chapter06 - List Views, Re-Sizing, and PopUps v00-03 03Feb12 + + Changes: + v00-01 25Aug11: First version + v00-02 03Dec11: Second version. + v00-03 03Feb12: Sorted out structure and added some text. + + + 6. An Application Workplace + +- the OrderManagerView + is the "home" window. It'll have a sign-on and password field in a sub-dialog + (also programmer-designed) which comes modally when the OrderManagemwent + window is established. Thus we demonstrate/discuss: + - programmatic layout (can only use userDialog) + - modal sub-window + - Handling icons and showing them. + - password dialog (shows asterisks when you type into it) - but can avoid + with startup param "skipPW" (but the dialog in the startup prog to show + use of ooDialog in normal rexx progs). + - Icons that when dbl-clicked startup other views + - Most menu items on OrderMgmgt dialog not implemented. + + - app function very absent - e.g. all dialog data is hard-coded - same for Cust, Prod, Order - no real data in any file. + - e.g. no function for "New Order" + 6.1 Program Structure + 6.1.1 Have to change .rc file manually to get icon showing properly - ResEdit makes it .\bmp\icon.ico + instead of .\order\bmp\icon.ico - even if you start resedit from Exercise06 and specify "resedit order\orderlistview.rc". + (Paths - esepc for ResEdit.) + 6.1.2 about use of .Application - not good for a shipped app - address later when "package" an app for shipping. + 6.1.3 Mention HRS class name changes to allow for possible packaging - all classes in a single file. + 6.1.3 Stand-alone testing + - incl how get dlgicons to show (Answer: rc file must be built and saved into the parent folder so that file path is right for invocation from the parent folder. ) + Ditto for ResDialog - compile the dll in the parent folder (check this!) + 6.1.4 Several place-holders for app functions - custmodel & custdata created for each showmodel. Fix in next exercise. + 6.1.5 One Folder per component - for resources such as bitmaps/icons for RcDialogs, need to run resedit from parent folder so that path to resource is correct when run the component from the parent folder. + 6.1.6 Reference to standalone code and the sample. Also must start from the Exercise06 folder - Customer\StartupCustomer - 'cos all paths in the code are relative to the Exercise06 folder. + 6.1.7 Why no Model/Data components for list views? + 6.1.8 Generally, in real life, creating something (Customer, Product, Order) requires a process different from merely updating something. This means a different GUI. But for this Guide, we'll assume Customer and Product get new records from a different place, + so new records can(in this sample app) be got by adding to the relevant data files. However, OrderForm and Order are different - so have a component each. + 6.1.9 The lists create a new instance for each list item - which is silly. + 6.1.10 Naming - explain diff between OrderMgmt & OrderMgr where appropriate. + +??? Mention standalone execution - point to sample code in samples and to App3. + + 6.2 Pop-Ups and Parents incl Non-Modal Dialogs + 6.2.1 How get pop-up to pop up away from parent? Answer - have to code it yourself. + 6.2.2 Starting a dialog from a dialog (incl interpret statement - pointer to later) + Use of "interpret", better would be to have a class object - but later we'll need interpret (won't we?) for the ObjectMgr. + Leave “interpret” in but mention it – say class object would be better - show how can be fixed in later exercise – where + this will be moved to a support class (ObjectMgr). + + 6.3 Icons and Lists + 6.3.1 The Icon View + - List Views - normal icon view - a "workplace" for Order Management.. + - Auto-resizing when window sized by user + + 6.3.2. The Report View + - Looking at the two list views, almost begs for a superclass. + - how do different fonts for the listView items + - Explain the surfacing of an instance in the listview dialogs - check the showModel method. + + 6.4 Re-Sizing Dialogs + + 6.5 Creating and Using Icons + - Icons - making them, getting 'em into the program. - + (1) Does the icon have to be a certain size, or will it get automatically shrunk? + (2) If it has to be a certain size, what's the size, and are there any restrictions as to the palette (I'm no expert, but using GIMP I'm given the option of saving as 16-bit, 24-bit or 32-bit color (or I think it's color!)). + (3) In the ~execute statement, I need to provide an ID. Does this mean I must have a *.rc file? Or can I invent an ID programmatically somehow - perhaps along the same lines as creating an ImageList? + (4) I want to assign my own icon as the dialog icon (that is, the icon at the extreme top left of a dialog). This is done (I understand) in the ~execute(..., <icon_ID> ) method (ooDialog Reference section 3.10.3). + + 6.6 Utility Dialogs - <- ??? <What's this??> (Is this the layer - process-entity-utility? Or just useful "canned" dialogs?) + - Mention password on startup to illustrate ooDialog use in otherwise non-ooDialog rexx programs. + "startup enterPW" - password is "Password". + + + + + +--> +<chapter id="chapSix"><title>An Application Workplace</title> +<indexterm><primary>OrderManager component</primary></indexterm> +<para>This chapter introduces the Order Management application, which is designed as a "workplace" + for a user handling sales orders. As such, it provides access to the required components - + customers, products, orders, and order forms. A common approach for a "workplace" dialog is to + provide an icon for each component that the user may wish to use. In the + <computeroutput>Exercise06</computeroutput> folder, run + <computeroutput>startup.rex</computeroutput>. The Order Management dialog opens, and + consists mainly of a List View containing four icons. Move the icons around; double-click them + and if a Customer, Product, or Order List appears then double-click a list item; re-size the + Order Management window; check out the menu items and the pushbuttons. As you see, while much + of the application function is absent, and the data is hard-coded, the essential parts of the + Order Management application mentioned in <xref linkend="chapFour"/> are visible. This chapter + addresses the following topics in the context of the Order Management application: <itemizedlist> + <listitem> + <para><xref linkend="chap06-struc"/></para> + </listitem> + <listitem> + <para><xref linkend="chap06-listviews"/>Icons and Lists</para> + </listitem> + <listitem> + <para><xref linkend="chap06-popups"/></para> + </listitem> + <listitem> + <para><xref linkend="chap06-resize"/></para> + </listitem> + <listitem> + <para><xref linkend="chap06-icons"/></para> + </listitem> + <listitem> + <para><xref linkend="chap06-utildlgs"/>Utility Dialogs</para> + </listitem> + </itemizedlist> + </para> + +<section id="chap06-struc"><title>Program Structure</title> <!-- Section 6.1 --> + <para>In Exercise06, each business component has its own folder: + Customer, Order, OrderMgr, and Product. Customer and Product are more or less identical + to the same components introduced in Exercises 04 and 05. + Placing each business component into a separate folder + helps promote high cohesion and low coupling in the software, + since the internals of each business component are opaque to other business components. + Thus another application (e.g. Customer Relationship + Management) might be able to make use of the Customer business component without change. + The Order Management business component is unlikely to be re-used in other applications as it is + a kind of "process" business component that "choreographs" the other business components. + To the user, creating a new sales order consists of "choreographing" the various business aspects + required - creating an Order Form (used to assemble the customer order), searching for and selecting a + specific Customer, searching for and selecting one or more Products, recording the quantities ordered, + and producing a Sales Order that is the "contract" between supplier and customer. Of course, the OrderManagement + component could be used by "higher-level" components such as business processes or workflows. In systems + organized according to these principles, invocation of components takes the form of a directed acyclic graph. + </para> + <para> + Within each business component are one or more component groups and components. For example, the Customer + business component contains two component groups: CustomerList and Customer. In turn, + each of these consists of one View component and one Model component. Both model components + share a single Data component. The Customer and Product + component groups are essentially identical to those introduced in Exercises 4 and 5 respectively. + </para> + <para> + The Order Management business component is, in this Exercise, implemented by a view class only. In fact, + there are two view classes, each in its own .rex file: <computeroutput>OrderMgmtBaseView</computeroutput> + and its subclass <computeroutput>OrderMgmtView</computeroutput>. + <computeroutput>OrderMgmtBaseView</computeroutput> + contains the code for handling a re-sizable dialog, and is a subclass of <computeroutput>UserDialog</computeroutput> + which is required for any dialog that is dynamically + re-sizable (see <xref linkend="chap06-resize"/>). <computeroutput>OrderMgmtView</computeroutput> contains the code + specific to the Order Management application. + The only reason for splitting the code like this is that it seems to fall happily into these two parts. This reduces + the amount of code in any one class or file, and so makes for better readability. + </para> + <para> + Note that the "data" of the OrderManagement business component is the set of icons and their associated data. + In Exercise06, this data is effectively embedded in the View classes. However, the code in the + <computeroutput>OrderMgmtView</computeroutput> class uses an <emphasis role="italic">interpret</emphasis> + instruction to launch views of the components represented by icons. Thus in principle, additional components + can be added without changing the code in the <computeroutput>OrdermgmtView</computeroutput> class. To support this, + a separate file - <computeroutput>RequiresList.rex</computeroutput> - contains the set of + <emphasis role="italic">::requires</emphasis> statements corresponding to the components that might be surfaced. + This is why the first executable statement in the file <computeroutput>OrderMgmtView.rex</computeroutput> is + <emphasis role="italic">call "OrderMgmt\RequiresList.rex"</emphasis>. Examples of possible additional components + could be a "commodities" component which shows + the commodities required to produce a given product; or a credit-check component that links to an external + credit-check agency. + </para> +</section> <!-- End of section 6.1 --> + + +<section id="chap06-listviews"><title>Icons and Lists</title> <!-- Section 6.2 --> + <indexterm><primary>ListView</primary></indexterm> + <indexterm><primary>Controls</primary><secondary>ListView</secondary></indexterm> + <indexterm><primary>Icons</primary><secondary>in a ListView</secondary></indexterm> + <para>The <computeroutput>ListView</computeroutput> should not be confused with <computeroutput>ListBox</computeroutput>; + a ListView (see ooDialog Reference chapter 20) is a souped-up ListBox with lots of additional features. In particular: + <itemizedlist> + <listitem><para>An item in a ListView can be a complex structure or "record" containing + multiple fields. One of these fields is termed the "label" of the item.</para></listitem> + <listitem><para>ListView items can be displayed in four different modes: + <itemizedlist> + <listitem><para>Icon view - each item appears as a full-sized icon with a label below it. + Items can be dragged around the ListView.</para></listitem> + <listitem><para>Small-icon view - each item appears as a small icon with a label to its right. + Items can be dragged around the ListView.</para></listitem> + <listitem><para>List view - each item appears as a label with an optional small icon to its left.</para></listitem> + <listitem><para>Report view - each item appears as a row in a table with an optional small icon to its left. + </para></listitem> + </itemizedlist> + The four different modes are well illustrated by the sample program <computeroutput>oodListViews.rex</computeroutput> + located in the <computeroutput>ooRexx\samples\oodialog</computeroutput> folder.</para></listitem> + </itemizedlist> + </para> + <para>In the Order Management application, the ListView control provides the main area of the Order Management dialog + where draggable icons (icon view) represent the various components of the application. + It also provides the tabular lists (report views) in the CustomerList, ProductList, and OrderList dialogs. + </para> + + <section id="chap06-listview-icon"><title>The Icon View</title> <!-- Section 6.2.1 --> + <para> + +<!-- + OMBV +1 ::attribute lv + + OMV +2 ::method init + expose records + self~createIconList 3 + records = self~initRecords 4 + +5 ::method initDialog + expose iconList records + self~lv~newListView(..) + self~lv~setImageList(..) + /*- Add icons (i.e. records) to the ListView: (actually used two hyphens at start - but oXygen doesn't like this.)*/ + do i=1 to records~items + self~lv~addRow(, i-1, records[i]~name) + end + +3 ::method createIconList + expose iconList + imgCustList = .Image~getImage( filename ) + ... + iconList = .ImageList~create(...) + iconList~add(imgCustList) /* item 0 in the list */ + ... + +4 ::method initRecords + expose records + records = .array~new() + rec = .directory~new + rec~ID = "CustomerList" + rec~name = "Customer List" + records[1] = rec + ... + return records + +6 ::method onDoubleClick + expose records + index = self~lv~focused /* lv is an attribute of OBMBV */ +--> + + The OrderManagement dialog uses the Icon View option of the ListView control. Five things are needed to produce an + icon view: first, create (or obtain) some icons; second, specify the <computeroutput>ICON</computeroutput> style for the ListView + control; third, create an ImageList from the icons (required by the ListView control); fourth, create a set of records + (one record per icon) to be loaded into the ListView; and fifth, load the icons and records into the ListView. + </para> + <orderedlist numeration="arabic"> + + <listitem> <!-- One --> + <para><emphasis role="bold"><emphasis role="italic">Produce the Icons</emphasis></emphasis></para> + <para>First, the large "icons" in the ListView are actually bitmaps. Icons and bitmaps have different formats, and different uses, + and there are a number of differences between them. The icons themselves + are in the folders of the relevant business components, so the icon for the Customer List, for example, is + <computeroutput>Exercise06\Customer\bmp\CustList.bmp</computeroutput>. (The <computeroutput>*.ico</computeroutput> + files are the dialog icons.) + A number of tools are available for creating and editing images, icons, bitmaps etc., + some of them providing conversion and re-sizing capabilities. One such is GIMP (GNU Image Manipulation Program) from + http://www.gimp.org. + <indexterm><primary>Bitmap Editor</primary></indexterm><indexterm><primary>Icon editor</primary></indexterm> + </para> + </listitem> + + <listitem> <!-- Two --> + <para><emphasis role="bold"><emphasis role="italic">Specify the ICON Style</emphasis></emphasis></para> + <para>The icon style for a ListView control is specified either in the + <computeroutput>*.rc</computeroutput> file as the + <computeroutput>LVS_ICON</computeroutput> (in ResEdit, set the "View" property to + "Icon"), or in a UserDialog, by creating the ListView control in the + <emphasis role="italic">initDialog</emphasis> method using the + <computeroutput>ICON</computeroutput> style (e.g.: + <computeroutput>self~createListView(IDC_ORDMGMT_ICONS, ... "ICON")</computeroutput> + where the first parameter is the ID for the ListView control.). </para> + </listitem> + + <listitem> <!-- 3 --> + <para><emphasis role="bold"><emphasis role="italic">Create an ImageList</emphasis></emphasis></para> + <para>The ListView documentation provides several ways to load icons. Probably the easiest is to create an + object of type <computeroutput>ImageList</computeroutput> (see ooDialog Reference + section 26.3) which is loaded into the ListView. In <computeroutput>OrderMgmtView</computeroutput>, this + is done in the <emphasis role="italic">createIconList</emphasis> method + (invoked from the <emphasis role="italic">init</emphasis> method) as follows: + <programlisting> + <![CDATA[ + ::METHOD createIconList PRIVATE + expose iconList + imgCustList = .Image~getImage("customer\bmp\CustList.bmp") + imgProdList = .Image~getImage("product\res\ProdList.bmp") + imgOrderList = .Image~getImage("order\bmp\OrderList.bmp") + imgOrderForm = .Image~getImage("order\bmp\OrderForm.bmp") + -- Boldly assume no errors in creating the Image List or in the ~getImage statements. + iconList = .ImageList~create(.Size~new(64, 64), .Image~toID(ILC_COLOR4), 4, 0) + iconList~add(imgCustList) -- item 0 in the list + iconList~add(imgProdList) -- item 1 in the list + iconList~add(imgOrderList) -- item 2 in the list + iconList~add(imgOrderForm) -- item 3 in the list + imgCustList~release + imgProdList~release + imgOrderList~release + imgOrderForm~release + return + ]]> + </programlisting> + For each icon, only two statements are required: create an Image from file then copy it to the ImageList (and a third, if you're + a polite programmer and try to clean up afterwards, release the image). + </para> + </listitem> + + <listitem> <!-- 4 --> + <para><emphasis role="bold"></emphasis>Create Records</para> + <para>Records are typically created in the <emphasis role="italic">init</emphasis> method (or in a method invoked from there). + In <computeroutput>OrderMgmgtView</computeroutput> the records are created in the <emphasis role="italic">initRecords</emphasis>) + method which is invoked from <emphasis role="italic">init</emphasis>. Each record has two fields: the text to appear beneath + the icon, and the class name of the dialog to be surfaced when a user double-clicks on an icon. The design choice for these records + is that each record will be a directory, and each directory will stored in an array. The array index of a record is equivalent + to the position of its icon in the ImageList (remembering that arrays are 1-based while ImageLists are 0-based). The code for loading + the record array is + as follows (showing only the Sales Orders item for brevity): + <programlisting> + <![CDATA[ + ::METHOD initRecords PRIVATE + expose records + records = .array~new() + ... + rec = .directory~new + rec~ID = "OrderList" + rec~name = "Sales Orders" + records[3] = rec + ... + return records + ]]> + </programlisting> + </para> + </listitem> + <listitem> <!-- 5 --> + <para><emphasis role="bold">Load the ImageList and the Records</emphasis></para> + <para>Loading icon images and records into the ListView is done in the + <emphasis role="italic">initDialog</emphasis>method: + <programlisting><![CDATA[ + ::METHOD initDialog + expose records iconList + self~initDialog:super + self~lv~setImageList(iconList, .Image~toID(LVSIL_NORMAL)) + do i=1 to records~items + self~lv~addRow(, i-1, records[i]~name) + end + ]]> + </programlisting> + After invoking the superclass, the icons in the ImageList are applied to the ListView control + using its <emphasis role="italic">setImageList</emphasis> method. The second parameter of this method + specifies the size of the icons by invoking + the Image class' <emphasis role="italic">toID</emphasis> method with the parameter <emphasis role="italic">LVSIL_NORMAL</emphasis> + (the flag for the icon view). The Image class is used to work with and manipulate images, + and is described in section 26.2 of the ooDialog Reference. The variable + <emphasis role="italic">self~lv</emphasis> is the list view proxy, <emphasis role="italic">lv</emphasis> being an + attribute of the <computeroutput>OrderMgmtBaseView</computeroutput> superclass. + The icons having been set, the records are then added + using the ListView's <emphasis role="italic">addRow</emphasis> method. The first parameter is the index of the list item + - if omitted, the record is added after the last. The second parameter is the index of the icon to be used with this record, and + the last parameter is the label for the list item - the string "Customer List" in the case of the first item added to the ListView in + <computeroutput>OrderMgmtView</computeroutput>. + </para> + </listitem> + </orderedlist> + + </section> <!-- End of section 6.2.1 --> + + <section id="chap06-listview-report"><title>The Report View</title> <!-- Section 6.2.2 --> + <para>Three of the icons in the Order Management dialog surface a list when double-clicked - Customers, Products, and Orders. + These three components are technically very similar - to the extent that a "list superclass" could perhaps be created. + For the meantime, however, this is not done, and each list is quite separate. However, their similarity means that discussing one + list - the Customer List - effectively addresses all. + </para> + <para></para> + </section> <!-- End of section 6.2.2 --> + + +</section> <!-- End of section 6.2 --> + + <section id="chap06-popups"><title>Non-Modal Dialogs</title> <!-- Section 6.3 --> + <para> + </para> + </section> <!-- End of section 6.3 --> + +<section id="chap06-resize"><title>Re-sizing Dialogs</title> <!-- Section 6.4 --> +<para>If you haven't already done so, try re-sizing the Order Management dialog. + The ListView containing the icons + expands to match the new window size, and one of the two pushbuttons moves as well, although their size + - unlike the size of the List View - does not change. This re-sizing function is only available + for a <computeroutput>UserDialog</computeroutput>, and requires a number of methods and lines of code. + ooDialog provides three samples of the resizing function in the folder + <computeroutput>ooRexx\samples\oodialog</computeroutput> folder - + the relevant programs being <computeroutput>dlgAreaUDemo.rex</computeroutput>, + <computeroutput>dlgAreaUDemoTwo.rex</computeroutput>, and + <computeroutput>dlgAreaUDemoThree.rex</computeroutput>. + <computeroutput>OrderManagementBaseView.rex</computeroutput> includes much of the code from the last + of these three samples. +</para> +<para> + The re-sizing function is provided by two ooDialog classes: <computeroutput>dlgAreaU</computeroutput> + and <computeroutput>dlgArea</computeroutput> (see ooDialog Reference sections 10.14 and 10.15). + An important constraint is that, because <computeroutput>dlgAreaU</computeroutput> parses + the source code of the <emphasis role="italic">defineDialog</emphasis> method in order to handle re-sizing, + it will only work with <computeroutput>UserDialog</computeroutput>, where the dialog template is created + through explicit control creation statements. In addition, since the source code is required at run-time, + it will not work if the source code is tokenized using <emphasis role="italic">rexxc</emphasis>. +</para> +<para> + Essentially, the dialog is first split into a number of areas - two areas for the + OrderManagement dialog. ears for . dilaog defines the A re-sizeable dialog - an excellent sample dialog - + </para> +</section> <!-- End of section 6.4 --> + + +<section id="chap06-icons"><title>Creating and Using Icons</title> <!-- Section 6.5 --> + <para>- Icons - making them, getting 'em into the program. - GIMP (GNU Image Manipulation Program) from + http://www.gimp.org +</para> +</section> <!-- End of section 6.5 --> + +<section id="chap06-utildlgs"><title>Utility Dialogs</title> <!-- Section 6.6 --> + <indexterm><primary>Password dialog</primary></indexterm> + <indexterm><primary>Utility routine</primary><secondary>PasswordBox</secondary></indexterm> + <para>A subject not yet mentioned is the use of ooDialog utility classes and routines in non-ooDialog ooRexx programs. + These are documented in Chapter 9 of the ooDialog Reference. The routines are very simple, and are often one-liners. + As an example, the Exercise06 startup program + provides for entry of a password using the (one-line) PasswordBox routine. + Invoking <emphasis role="italic">startup enterPW</emphasis> produces a password box that will accept the password + "Password". If you get the password wrong, the startup routine will silently end. The code is as follows: + <programlisting> + <![CDATA[ + parse arg pwOption + if pwOption = "enterPW" then do + pwd = PasswordBox("Please enter your password","Sign In") + if pwd \= "Password" then exit + end + .OrderMgmtView~newInstance + ::REQUIRES "OrderMgmt\OrderMgmtView.rex" + ]]> + </programlisting> + + </para> +</section> <!-- End of section 6.6 --> + +</chapter> + This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mie...@us...> - 2012-02-08 15:42:23
|
Revision: 7511 http://oorexx.svn.sourceforge.net/oorexx/?rev=7511&view=rev Author: miesfeld Date: 2012-02-08 15:42:16 +0000 (Wed, 08 Feb 2012) Log Message: ----------- oodguide - fix tags and errors Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/Chapter05.xml docs/trunk/oodguide/Chapter06.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-02-08 15:03:21 UTC (rev 7510) +++ docs/trunk/oodguide/Chapter04.xml 2012-02-08 15:42:16 UTC (rev 7511) @@ -525,7 +525,7 @@ these menu items. Note that the "Print" method does nothing other than show a messagebox saying that this function is not implemented. Best practice suggests that an explanatory message is much better than the alternative (comment out - the <emphisis role="italic">print</emphisis> method to see what that alternative is).</para> + the <emphasis role="italic">print</emphasis> method to see what that alternative is).</para> <para>But before the menu actions will work, the <emphasis role="italic">menuBar</emphasis> object must be associated with the dialog object. This is done by this statement (at the beginning of the <emphasis role="italic">initDialog</emphasis> method): Modified: docs/trunk/oodguide/Chapter05.xml =================================================================== --- docs/trunk/oodguide/Chapter05.xml 2012-02-08 15:03:21 UTC (rev 7510) +++ docs/trunk/oodguide/Chapter05.xml 2012-02-08 15:42:16 UTC (rev 7511) @@ -199,8 +199,8 @@ a minor file management challenge in the runtime environment. A ResDialog class, on the other hand, has only two files: the *.dll and the *.h. </para> <para>See <link linkend="apx-dlgsequences" endterm="dlgsequences.title"></link> for a - comparison of dialog startup methods comparing an <computeroutpur>RcDialog</computeroutpur>, - a <computeroutpur>ResDialog</computeroutpur> and a <computeroutpur>UserDialog</computeroutpur>.</para> + comparison of dialog startup methods comparing an <computeroutput>RcDialog</computeroutput>, a + <computeroutput>ResDialog</computeroutput> and a <computeroutput>UserDialog</computeroutput>.</para> </section> <!-- End of section 5.2.2 --> </section> Modified: docs/trunk/oodguide/Chapter06.xml =================================================================== --- docs/trunk/oodguide/Chapter06.xml 2012-02-08 15:03:21 UTC (rev 7510) +++ docs/trunk/oodguide/Chapter06.xml 2012-02-08 15:42:16 UTC (rev 7511) @@ -87,7 +87,7 @@ 6.2.1 How get pop-up to pop up away from parent? Answer - have to code it yourself. 6.2.2 Starting a dialog from a dialog (incl interpret statement - pointer to later) Use of "interpret", better would be to have a class object - but later we'll need interpret (won't we?) for the ObjectMgr. - Leave “interpret” in but mention it – say class object would be better - show how can be fixed in later exercise – where + Leave "interpret" in but mention it, say class object would be better - show how can be fixed in later exercise where this will be moved to a support class (ObjectMgr). 6.3 Icons and Lists This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-03-31 22:45:23
|
Revision: 7720 http://oorexx.svn.sourceforge.net/oorexx/?rev=7720&view=rev Author: osims Date: 2012-03-31 22:45:16 +0000 (Sat, 31 Mar 2012) Log Message: ----------- Modified Paths: -------------- docs/trunk/oodguide/Chapter02.xml docs/trunk/oodguide/Chapter05.xml docs/trunk/oodguide/Chapter06.xml Modified: docs/trunk/oodguide/Chapter02.xml =================================================================== --- docs/trunk/oodguide/Chapter02.xml 2012-03-31 20:01:56 UTC (rev 7719) +++ docs/trunk/oodguide/Chapter02.xml 2012-03-31 22:45:16 UTC (rev 7720) @@ -38,10 +38,11 @@ ######################################################################### --> -<!-- Chapter02 - In The Beginning v00-06 06Feb12 +<!-- Chapter02 - In The Beginning v00-07 31Mar12 v00-04 26Jly11 v00-05 11Aug11: Minor corrections to match exercise numbers. v00-06 06Feb12: Code change - resource number -1 changed to 101. + v00-07 31Mar12: Correction to role=italic (no quotes). --> <chapter id="chapTwo"><title>In The Beginning</title> @@ -299,7 +300,7 @@ (and so far only) "words of wisdom". </para> <para> -Now we need to make the <emphasis role=italic>More wisdom</emphasis> button work, +Now we need to make the <emphasis role="italic">More wisdom</emphasis> button work, which we now do in <computeroutput>Wow2.rex</computeroutput>. </para> Modified: docs/trunk/oodguide/Chapter05.xml =================================================================== --- docs/trunk/oodguide/Chapter05.xml 2012-03-31 20:01:56 UTC (rev 7719) +++ docs/trunk/oodguide/Chapter05.xml 2012-03-31 22:45:16 UTC (rev 7720) @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter05 - Using Binary Resource Dialogs v00-08 21Feb12 +<!-- Chapter05 - Using Binary Resource Dialogs v00-09 31Mar12 5.1 - Dialog Initiation - using the newInstance class method. 5.2 - Compiling a binary resource file 5.3 - Differences between RcDialog and ResDialog @@ -55,6 +55,7 @@ over-ride normal Windows behaviour). v00-07 26Jan12: Various minor updates to wording. v00-08 21Feb12: Added section 5.3.5 about Min/Max buttons on a dialog. + v00-09 31Mar12: Correction to an xref tag. --> <chapter id="chapFive"> @@ -433,7 +434,7 @@ <!-- Section 5.3.4.2 --> <para>Making the image respond to mouse clicks is merely a matter of defining the image-static control in the *.rc file as having the style "SS_NOTIFY" which, using - ResEdit (and as mentioned in <xref linkend="chap05-defimage">), merely requires the + ResEdit (and as mentioned in <xref linkend="chap05-defimage"/>), merely requires the "Notify" attribute to be set to "True". When the image is double-clicked, the dialog is sent an event. This event is connected to the <emphasis role="italic">showMsgBox</emphasis> method by the statement Modified: docs/trunk/oodguide/Chapter06.xml =================================================================== --- docs/trunk/oodguide/Chapter06.xml 2012-03-31 20:01:56 UTC (rev 7719) +++ docs/trunk/oodguide/Chapter06.xml 2012-03-31 22:45:16 UTC (rev 7720) @@ -38,7 +38,7 @@ ######################################################################### --> -<!-- Chapter06 - List Views, Re-Sizing, and PopUps v00-05 31Mar12 +<!-- Chapter06 - List Views, Re-Sizing, and PopUps v00-06 31Mar12 Changes: v00-01 25Aug11: First version @@ -46,6 +46,7 @@ v00-03 03Feb12: Sorted out structure; added text. v00-04 ??Feb12 v00-05 31Mar12: Almost completed. + v00-06 31Mar12: Corrected to chapter 6.2.2 title (title link missing) 6 "An Application Workplace" chapSix 6.1 Program Structure chap06-struc @@ -455,7 +456,7 @@ </para> </section> <!-- End of Section 6.2.1 --> - <section id="chap06-popups-offset"><title>Offsetting Dialogs</title> <!-- Section 6.2.2 --> + <section id="chap06-popups-offset"><title id="offsetting.title">Offsetting Dialogs</title> <!-- Section 6.2.2 --> <para>When creating a resource file for a dialog, it is unusual to define the position of the dialog on the screen. Instead, the option to center the dialog in the screen is often used. This is the option applied in Exercise 6. However, when a number of different dialogs This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-04-02 16:11:43
|
Revision: 7731 http://oorexx.svn.sourceforge.net/oorexx/?rev=7731&view=rev Author: osims Date: 2012-04-02 16:11:32 +0000 (Mon, 02 Apr 2012) Log Message: ----------- Chap 2 - Add para on windows vs dialogs; change all uses of "window" to "dialog"; other minor corrections. Chap 4 - Corrected text about create menubar (last param now not there) Modified Paths: -------------- docs/trunk/oodguide/Chapter02.xml docs/trunk/oodguide/Chapter04.xml Modified: docs/trunk/oodguide/Chapter02.xml =================================================================== --- docs/trunk/oodguide/Chapter02.xml 2012-04-02 06:24:11 UTC (rev 7730) +++ docs/trunk/oodguide/Chapter02.xml 2012-04-02 16:11:32 UTC (rev 7731) @@ -38,60 +38,82 @@ ######################################################################### --> -<!-- Chapter02 - In The Beginning v00-07 31Mar12 +<!-- Chapter02 - In The Beginning v00-08 02Apr12 v00-04 26Jly11 v00-05 11Aug11: Minor corrections to match exercise numbers. v00-06 06Feb12: Code change - resource number -1 changed to 101. v00-07 31Mar12: Correction to role=italic (no quotes). + v00-08 02Apr12: Add para on windows vs dialogs; change all uses of "window" + to "dialog". --> <chapter id="chapTwo"><title>In The Beginning</title> <indexterm><primary>overview</primary></indexterm> <para> The whole purpose of ooDialog is to enable ooRexx developers to provide users with - a graphical user interface or "GUI". A GUI is a collection of windows. Each window contains a - number of controls, such as edit controls, push buttons, list boxes, and so forth. The user - keys data into controls (e.g. types into an edit control) or manipulates controls with a mouse - (e.g. selects an item in a listbox). Some of these actions invoke application code which in turn - makes some change to the window, causes some other action such as data access, or both. + a graphical user interface or "GUI". A GUI is a collection of windows and dialogs. + Each contains a number of controls, such as edit controls, push buttons, list + boxes, and so forth. The user keys data into controls (e.g. types into an edit + control) or manipulates controls with a mouse (e.g. selects an item in a + listbox). Some of these actions invoke application code which in turn + makes some change to the window or dialog, causes some other action such as + data access, or both. </para> <para> +Before continuing, it's worth distinguishing between a "window" and a "dialog". +A dialog is a stylized form of window that is familiar to most users. As dialogs +have evolved they have become more useful, and can now provide the user interface +function for many applications. Also, a dialog is drawn by the operating system, +while drawing a normal window is mostly the programmer's responsibility. Thus +producing an application needs much less programming work because the Rexx +programmer doesn't need to know or understand the low-level mechanics of drawing +to the screen. In summary, dialogs now have many window functions, and are much +easier to produce. And it's this that makes ooDialog a particularly useful +extension to a Rexx interpreter. +</para> +<para> There are three general areas of concern in designing an ooDialog application: <itemizedlist> -<listitem><para>Designing the appearance of the window</para></listitem> -<listitem><para>Designing the desired user interactions with the window</para></listitem> +<listitem><para>Designing the appearance of a dialog</para></listitem> +<listitem><para>Designing the desired user interactions with the dialog</para></listitem> <listitem><para>Designing the code that implements both appearance and interactions</para></listitem> </itemizedlist> </para> <para> And there are three corresponding areas of implementation concern: <itemizedlist> -<listitem><para>Laying out the window</para></listitem> -<listitem><para>Implementing the actions requested by users of a window</para></listitem> -<listitem><para>Providing the results of those actions to the user on the window.</para></listitem> +<listitem><para>Laying out the dialog</para></listitem> +<listitem><para>Implementing the actions requested by users of a dialog</para></listitem> +<listitem><para>Showing the results of those actions to the user.</para></listitem> </itemizedlist> </para> <para> - This document does not pretend to be a guide to best practice in the areas of design, although - it tries to conform with good design principles. However, this document - <emphasis role="italic">does</emphasis> aim to familiarize readers with the essentials of - ooDialog application implementation. + This document does not pretend to be a guide to best practice in the areas of + design, although it tries to conform with good design principles. However, + this document <emphasis role="italic">does</emphasis> aim to familiarize + readers with the essentials of ooDialog application implementation. </para> <para> - So, before starting the first exercise, please make sure that you have downloaded and installed the - latest versions of ooRexx and ooDialog. Please also run one or more of the samples in - <computeroutput>Open Object Rexx --> ooRexx Samples --> ooDialog </computeroutput> to ensure - that your installation works properly. + So, before starting the first exercise, please make sure that you have + downloaded and installed the latest versions of ooRexx and ooDialog. Please + also run one or more of the samples in <computeroutput>Start --> All Programs + --> Open Object Rexx --> ooRexx Samples --> ooDialog </computeroutput> to + ensure that your installation works properly. </para> +<para><emphasis role="bold"><emphasis role="italic">And please do use the + ooDialog Reference manual for the details on any ooDialog class, method + or function mentioned in this Guide.</emphasis></emphasis> +</para> <section id="sctGettingStarted"><title>Getting Started</title> <para> - The first exercise creates and displays a blank window with the title "Hello World!". - Try running it - it's the file <computeroutput>HelloWorld.rex"</computeroutput> in + The first exercise creates and displays a blank dialog with the title "Hello World!". + Try running it - it's the file <computeroutput>HelloWorld.rex</computeroutput> in the <computeroutput>Exercises\Exercise02</computeroutput> folder (exercise folder - numbers map to chapter numbers). <xref linkend="fig01"/> shows what you should see. + numbers map to chapter numbers). <xref linkend="fig01"> shows what you should see. </para> <para> - The Command Prompt window that appears with the <emphasis role="italic">Hello World</emphasis> window can be can be useful + The Command Prompt window that appears with the <emphasis role="italic">Hello World</emphasis> + dialog can be can be useful for debugging, but it can be dispensed with, and later we'll find out how. For now, let's look at the <emphasis role="italic">Hello World</emphasis> code (excluding comments): </para> @@ -115,16 +137,16 @@ and assigns the instance to the variable <emphasis role="italic">dlg</emphasis> (the <computeroutput>HelloWorld</computeroutput> class is defined in the third part of the code). The second statement invokes the <emphasis role="italic">execute</emphasis> method of - <computeroutput>HelloWorld</computeroutput>, and it is this that displays the window. + <computeroutput>HelloWorld</computeroutput>, and it is this that displays the dialog. The first parameter <emphasis role="italic">SHOWTOP</emphasis> is one of several ways of defining - how the window is surfaced (see section 3.10.3 of the ooDialog reference for details). - The second parameter states that the icon at the extreme top left of the window should be the + how the dialog is surfaced (see the ooDialog reference for details). + The second parameter states that the icon at the extreme top left of the dialog should be the normal ooRexx icon. This graphic is termed a "resource" in ooDialog, and there are a number - of such predefined constants (see section 2.3.3 of the ooDialog reference). + of such predefined constants (again, see the ooDialog reference for details). </para> <para> Note that the usual naming conventions are observed: upper camel case for classes - (e.g. <computeroutput>HelloWorld</computeroutput> and lower camel case for + (e.g. <computeroutput>HelloWorld</computeroutput>) and lower camel case for variables (including of course instance variables - e.g. <emphasis role="italic">dlg</emphasis>). </para> <para> @@ -156,23 +178,23 @@ <programlisting> <![CDATA[ ::CLASS HelloWorld SUBCLASS UserDialog - ::METHOD init - forward class (super) continue - self~create(30, 30, 257, 123, "Hello World", "CENTER") + ::METHOD init + forward class (super) continue + self~create(30, 30, 257, 123, "Hello World", "CENTER") ]]> </programlisting> The first line defines a class called <computeroutput>HelloWorld</computeroutput> as a subclass of - the ooDialog-provided class <computeroutput>UserDialog</computeroutput> (see Chapter 7 of the - ooDialog Reference for full details). + the ooDialog-provided class <computeroutput>UserDialog</computeroutput> + (and yet again but finally, see the ooDialog Reference for full details). Among other things, <computeroutput>UserDialog</computeroutput> enables the programmer to define - the window layout in code. This can get cumbersome in more complex dialogs, and later we'll - meet a simpler way of defining the window layout. + the dialog layout in code. This can get cumbersome in more complex dialogs, and later we'll + meet a simpler way of defining the dialog layout. </para> <para> The second line defines the <emphasis role="italic">init</emphasis> method of <computeroutput>HelloWorld</computeroutput>, and the third line forwards the <emphasis role="italic">init</emphasis> message to the superclass which then - does the heavy work of creating the window (see Chapter 3 of the ooDialog Reference). + does the heavy work of creating the dialog. But why use <emphasis role="italic">forward</emphasis> instead of <emphasis role="italic">self~init:super</emphasis>? The reason is that <emphasis role="italic">forward</emphasis> applies not only to the method but @@ -181,38 +203,37 @@ <para> Finally, the last line sends a <emphasis role="italic">create</emphasis> message to <emphasis role="italic">self</emphasis> and hence to <computeroutput>UserDialog</computeroutput>. - This method defines the "template" to be used for the dialog window - (see Chapter 7 of the Windows ooDialog Reference). The parameters are as follows: + This method defines the "template" to be used for the dialog. The parameters are as follows: <itemizedlist> <listitem><para> The first two parameters define, in "dialog units", the x and y position on the screen - of the top left corner of the window. Dialog units (rather than pels) are used to + of the top left corner of the dialog. Dialog units (rather than pels) are used to provide device independence. </para></listitem> <listitem><para> The third and fourth parameters define the width and height of the dialog, again in dialog units. </para></listitem> <listitem><para> - The fifth parameter is the window's title, and the last parameter - - <computeroutput>CENTER</computeroutput> - is the dialog "style" (see ooDialog Reference chapter 7.3 - for the full set of styles). <computeroutput>CENTER</computeroutput> states - that regardless of the first two parameters, the dialog window will be positioned in + The fifth parameter is the dialog's title, and the last parameter - + <computeroutput>CENTER</computeroutput> - is the dialog "style" (of which + there are several). <computeroutput>CENTER</computeroutput> states + that regardless of the first two parameters, the dialog will be positioned in the center of the screen. Styles are an important part of dialog definition. Try removing the <computeroutput>CENTER</computeroutput> parameter (and its preceding comma of course) and see what happens. Then replace the <computeroutput>CENTER</computeroutput> parameter, and (just to make sure that you've replaced it correctly) run the program again, - and this time try to size the window. You can't. Then replace + and this time try to size the dialog. You can't. Then replace <computeroutput>CENTER</computeroutput> by <computeroutput>CENTER THICKFRAME</computeroutput> - and re-run the program. The window now has a sizable border. Thus styles + and re-run the program. The dialog now has a sizable border. Thus styles not only affect appearance, they can also define behavior. </para></listitem> </itemizedlist> </para> <para>With this instance of the <computeroutput>HelloWorld</computeroutput> class having - been set up properly, the window is actually surfaced (made visible) by the + been set up properly, the dialog is actually surfaced (made visible) by the <emphasis role="italic">execute</emphasis> message (handled by HelloWorld's superclass) - sent by the second statement in the first part of the program which was: + sent by the second statement in the program which was: <programlisting> <![CDATA[ dlg~execute("SHOWTOP", IDI_DLG_OOREXX) @@ -226,31 +247,31 @@ </section> <section id="visBehavior"><title>Visible Behavior</title> -<para>This section is in two parts. First we create a window that invites the user to press a button +<para>This section is in two parts. First we create a dialog that invites the user to press a button for more "words of wisdom" - but the button doesn't work. Second, we make the button work. In this way, -we both add to the way windows are populated with controls, and also show how user input is handled. +we both add to the way dialogs are populated with controls, and also show how user input is handled. </para> <section id="vizBehavior1"> <!-- should be numbered 2.2.1 I think) --> - <title>Adding Controls to the Window</title> + <title>Adding Controls to the Dialog</title> <para> First, try running <computeroutput>Wow.rex</computeroutput> from the <computeroutput>Exercises\Exercise02</computeroutput> folder ("Wow" being short for "Words of Wisdom"). You should see a dialog entitled "Words of Wisdom" which is blank with the exception of some (alleged) words of wisdom - and two push-buttons. One of these does nothing, the other (Cancel) closes the window. - These buttons are examples of "controls" - sometimes called "widgets" - that populate a window - and enable both display of information and user interaction with the window. + and two push-buttons. One of these does nothing, the other (Cancel) closes the dialog. + These buttons are examples of "controls" - sometimes called "widgets" - that populate a dialog + and enable both display of information and user interaction with the dialog. </para> <para> Now let's look at the code. - The first seven lines (excluding comments, spacing lines and the window title) + The first seven lines (excluding comments) are essentially the same as the first seven in <computeroutput>HelloWorld.rex</computeroutput>: <programlisting> <![CDATA[ dlg = .WordsOfWisdom~new dlg~execute("SHOWTOP", IDI_DLG_OOREXX) ::REQUIRES "ooDialog.cls" - ::CLASS 'MyDialog' SUBCLASS UserDialog + ::CLASS 'WordsOfWisdom' SUBCLASS UserDialog ::METHOD init forward class (super) continue self~create(30, 30, 257, 123, "Words of Wisdom", "CENTER") @@ -262,7 +283,7 @@ ::METHOD defineDialog self~createPushButton(901, 142, 99, 50, 14, "DEFAULT", "More wisdom") self~createPushButton(IDCANCEL, 197, 99, 50, 14, ,"Cancel") - self~createStaticText(101, 40, 40, 200, 20, , - + self~createStaticText(-1, 40, 40, 200, 20, , - "Complex problems have simple solutions"||.endofline||"- which are wrong.") ]]> </programlisting> @@ -270,38 +291,43 @@ statements each of which creates a control. The first two each create a pushbutton: <itemizedlist> <listitem><para> - A "More Wisdom" pushbutton, which has been given the resource ID of "901" (the first parameter). - Controls are identified - by numbers (or as we'll see later by symbolic names). You can pick any number - except numbers 0-50 which are reserved. Each control should have a different number (although there + A "More Wisdom" pushbutton, which has been given the resource ID of "901" + (the first parameter). Controls are identified + by numbers (IDs) or, as we'll see later, by symbolic names. You can pick + any number although numbers -1 and 1 through 50 are pre-defined by ooDialog. + For example, resource ID "1" is an "OK" button. + Resource numbers or IDs identify controls to the underlying + Windows platform, and can be given in either numeric or symbolic form, as will + be discussed in Chapter 3. + <indexterm><primary>Resource numbers</primary></indexterm> + Each control should have a different number (although there are some situations, which will be met later, where it's useful for two or more controls to have the same number). The next four parameters define the - position of the button in the window, and the sixth ("DEFAULT") specifies that this button + position of the button in the dialog, and the sixth ("DEFAULT") specifies that this button is to be the default action for pressing the enter key. The seventh parameter - is the text shown on the button. See ooDialog Reference section 7.10.3.2 for full details of - the <emphasis role='italic'>createPushButton</emphasis> method. + is the text shown on the button. </para></listitem> <listitem><para> A "Cancel" pushbutton, whose ID <emphasis role="italic">IDCANCEL</emphasis> - makes this button perform the standard window cancel action - that is, close - the window without saving any changes. (An OK button should save - any changes made by the user, and then close the window - preferably with an - intervening "Save changes?" message box with options "Yes", "NO, and "Cancel".) + makes this button perform the standard dialog cancel action - that is, close + the dialog without saving any changes. (An OK button should save + any changes made by the user, and then close the dialog - preferably with an + intervening "Save changes?" message box with options "Yes", "No, and "Cancel".) </para></listitem> </itemizedlist> The third statement creates some static text (text that cannot be changed by the user), - with the text itself as the last parameter. The first parameter is the resource number, - "101". (Resource numbers or IDs identify controls to the underlying - Windows platform, and can be given in either numeric or symbolic form, as will - be discussed in Chapter 3. Any number above 50 can be used - "101" is merely the author's - mild preference. See also ooDialog Reference section 2.3.7.) The next four parameters define - the size and position of the static text control. + with the text itself as the last parameter. The first parameter is the resource number + "-1" which is the pre-defined resource ID for a Static Text control (although + you can use other numbers above 50 - for example if you want to distinguish + between different static text controls or when you want to programmatically change + the text - neither of which is a requirement here). + The next four parameters define the size and position of the static text control. Last but not least is the text to be displayed. This text comprises the initial (and so far only) "words of wisdom". </para> <para> -Now we need to make the <emphasis role="italic">More wisdom</emphasis> button work, -which we now do in <computeroutput>Wow2.rex</computeroutput>. + Now we need to make the <emphasis role="italic">More wisdom</emphasis> button work, + which we now do in <computeroutput>Wow2.rex</computeroutput>. </para> </section> @@ -322,11 +348,11 @@ principle of UI design is that of least astonishment: if the user is astonished by what the computer is doing in response to a wholly innocent user interaction with some UI widget, then that principle is breached. Of course, astonishment can be pleasant or unpleasant; and - if you can create ooDialog UIs which <emphasis role="italic">pleasantly</emphasis> astonish + if you can create ooDialog GUIs which <emphasis role="italic">pleasantly</emphasis> astonish their users, then you probably don't need to read this Guide. </para> <para> - In ooDialog, there are a number of ways of connecting a user action on an "actionable" widget + In ooDialog, there are a number of ways of connecting a user action to a method. Now ooDialog depends on the underlying Windows GUI software infrastructure, so a user action is actually signaled by that infrastructure, and ooDialog connects that event to a method in the ooRexx dialog object. So the source of the event (the user action) is not ooDialog. @@ -340,7 +366,7 @@ And, since a pushbutton control provides for just such an approach, that's what we'll do here. The first lines of code in <computeroutput>Wow2.rex</computeroutput> - down to the <emphasis role="italic">defineDialog</emphasis> method - are almost identical to those of - <computeroutput>Exercise02a.rex</computeroutput>, with only one significant change. + <computeroutput>wow.rex</computeroutput>, with only one significant change. The method is as follows: <programlisting> <![CDATA[ @@ -352,15 +378,18 @@ </programlisting> </para> <para> - The significant change is in the first statement - <emphasis role="italic">self~createPushButton</emphasis> + There are two significant changes. Firstly, the statement + - <emphasis role="italic">self~createPushButton</emphasis> - has an additional parameter <emphasis role="italic">okClicked</emphasis>. This is the name of the method that is automatically invoked by ooDialog when the user - clicks on the <emphasis role="italic">More wisdom</emphasis> pushbutton. Other changes are trivial - - the statement <emphasis role="italic">self~createStaticText</emphasis> on the last line has more space - allocated in which the the text is displayed, and the initial text has changed to "Click 'More wisdom'". + clicks on the <emphasis role="italic">More wisdom</emphasis> pushbutton. Secondly, + the statement <emphasis role="italic">self~createStaticText</emphasis> has the + ID 101 rather than -1 since we want to have the text changed when the "More Wisdom" + button is pressed. Also, the space for text to be displayed has increased from + 20 to 40, and the initial text has been changed to "Click 'More wisdom'". </para> <para> - The major addition to the program is the new <emphasis role="italic">okClicked</emphasis> method that + However, the major change to the program is the new <emphasis role="italic">okClicked</emphasis> method that picks a "words of wisdom" text and displays it. Pseudocode for this method is as follows: <programlisting> <![CDATA[ @@ -387,9 +416,9 @@ not good. Aside from performance considerations (the code creates and populates a new array each time the button is clicked), there is absolutely no separation of design concerns. And this is arguably the most important thing for any application - especially one with a GUI. - There are at least three important areas of design concern - UI display and interaction, the - "business" (here the business of selecting the text), and the provision of persistent data. - But we'll start to fix this in the next chapter. + There are three important areas of design concern - UI display and interaction, the + "business" that the dialog performs (here the business of selecting the text), + and the provision of persistent data. But we'll start to fix this in the next chapter. </para> </section> Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-04-02 06:24:11 UTC (rev 7730) +++ docs/trunk/oodguide/Chapter04.xml 2012-04-02 16:11:32 UTC (rev 7731) @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter04 - Using Resource Dialogs v00-09 25Jan12 +<!-- Chapter04 - Using Resource Dialogs v00-10 01Apr12 4.1 Naming and Coding Conventions 4.1.1 Naming Conventions 4.1.2 Coding Conventions @@ -57,6 +57,7 @@ in CustomerView code. v00-08 25Jan12: A number of individually minor corrections. v00-09 25Jan12: Oops - forgot about hitting Esc and disappearing the dialog. + v00-10 01Apr12: Corrected text about create menubar (last param now not there). --> <chapter id="chapFour"> <title>Using Resource Dialogs</title> @@ -486,8 +487,7 @@ <computeroutput>UNGUARDED</computeroutput>. In general, an event handler should be unguarded to preclude the possibility that some guarded method in the dialog object is executing at the time the event notification is generated. For further information, see - ooDialog Reference sections 2.2.4, the introduction to section 5.7, and also section - 5.7.1. </para> + the ooDialog Reference. </para> <para>Specification of active controls is generally done in the <emphasis role="italic" >initDialog</emphasis> method. Indeed, in the <computeroutput>CustomerView</computeroutput> class, specification of active controls @@ -495,11 +495,11 @@ <para> Note that menubar actions are not specified. This is because the menu items in <computeroutput>CustomerView.rex</computeroutput> are "auto-connected" (see <link linkend="apx-connections" endterm="connections.title"></link>). Auto-connection is specified - in the second-last parameter of the <emphasis role="italic">.ScriptMenuBar~new</emphasis> - statement (see section 25.6 of the ooDialog Reference) in the <emphasis role="italic" - >createMenuBar</emphasis> method: <programlisting> + in the last parameter of the following <emphasis role="italic">.ScriptMenuBar~new</emphasis> + statement in the <emphasis role="italic">createMenuBar</emphasis> method: + <programlisting> <![CDATA[ - menuBar = .ScriptMenuBar~new("CustomerView.rc", "IDR_CUST_MENU", , , .true, self) + menuBar = .ScriptMenuBar~new("CustomerView.rc", "IDR_CUST_MENU", , , .true) ]]> </programlisting> <indexterm> @@ -522,10 +522,10 @@ </programlisting> Spaces and trailing dots are stripped, giving method names of "NewCustomer", "Update", "Print", and "LastOrder". In the "MenuBar Methods" part of the <computeroutput>CustomerView</computeroutput> code, a method is provided for all of - these menu items. Note that the "Print" method does nothing other than show a - messagebox saying that this function is not implemented. Best practice suggests - that an explanatory message is much better than the alternative (comment out - the <emphasis role="italic">print</emphasis> method to see what that alternative is).</para> + these menu items. Note that the "print" and "newCustomer" methods do nothing other than show a + messagebox saying that the function is not implemented. Best practice suggests + that an explanatory message is much better than the alternative (to see what this alternative + is, try commenting outthe <emphasis role="italic">print</emphasis> method).</para> <para>But before the menu actions will work, the <emphasis role="italic">menuBar</emphasis> object must be associated with the dialog object. This is done by this statement (at the beginning of the <emphasis role="italic">initDialog</emphasis> method): This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-04-21 23:35:33
|
Revision: 7773 http://oorexx.svn.sourceforge.net/oorexx/?rev=7773&view=rev Author: osims Date: 2012-04-21 23:35:26 +0000 (Sat, 21 Apr 2012) Log Message: ----------- Very minor mod to Chap3; corrections made to Chapter 6 after reading the PDF. Chapter 6 now finished (I hope). Modified Paths: -------------- docs/trunk/oodguide/Chapter03.xml docs/trunk/oodguide/Chapter06.xml Modified: docs/trunk/oodguide/Chapter03.xml =================================================================== --- docs/trunk/oodguide/Chapter03.xml 2012-04-21 20:54:50 UTC (rev 7772) +++ docs/trunk/oodguide/Chapter03.xml 2012-04-21 23:35:26 UTC (rev 7773) @@ -38,12 +38,13 @@ ######################################################################### --> -<!-- Chapter03 - Re-Structuring the Code v00-06 21Apr12 +<!-- Chapter03 - Re-Structuring the Code v00-07 21Apr12 v00-04 12Aug11: Changed names of rex files and view classes in the code; text changed to match, plus some minor corrections. v00-05 02Apr12: Minor corrections. v00-06 21Apr12: Change book ref. Also add stuff on "components". + v00-07 21Apr12: Added a title link ("reduce-cplg") --> <chapter id="chapThree"><title>Re-Structuring the Code</title> <indexterm><primary>code structure</primary></indexterm> @@ -211,7 +212,7 @@ we'll leave it as it is. </para> </section> </section> -<section id="chap03-cplg"><title>Reducing Coupling</title><!-- section 3.2 --> +<section id="chap03-cplg"><title id="reduce-cplg">Reducing Coupling</title><!-- section 3.2 --> <indexterm><primary>Coupling</primary></indexterm> <para>The three classes in <computeroutput>Wow3.rex</computeroutput> are reasonably decoupled: the dialog is in one class, the business logic (such as it is) in another, and the data in a Modified: docs/trunk/oodguide/Chapter06.xml =================================================================== --- docs/trunk/oodguide/Chapter06.xml 2012-04-21 20:54:50 UTC (rev 7772) +++ docs/trunk/oodguide/Chapter06.xml 2012-04-21 23:35:26 UTC (rev 7773) @@ -96,8 +96,9 @@ of the application function is absent, the data is hard-coded, and there is some redundancy (e.g. every time you double-click on an item in a list view a new Model and Data object is created), the essential parts of the Order Management application mentioned in - <xref linkend="chapFour"/> are visible. This chapter addresses the following topics in the context + <xref linkend="chapFour"> are visible. This chapter addresses the following topics in the context of the Order Management application: <itemizedlist> + <!-- Was <xref linkend="chapFour"/> which gave "Chapter 4>"!!! Try the above instead. --> <listitem> <para><link linkend="chap06-struc" endterm="progstruc.title"></link></para> </listitem> @@ -153,7 +154,7 @@ <computeroutput>OrderMgmtView</computeroutput> and its superclass <computeroutput>OrderMgmtBaseView</computeroutput>. <computeroutput>OrderMgmtBaseView</computeroutput> contains the code for handling a re-sizable dialog, and is a subclass of <computeroutput>UserDialog</computeroutput> which - is required for any dialog that is dynamically re-sizable (see <xref linkend="chap06-resize"/>). + is required for any dialog that is dynamically re-sizable (see <xref linkend="chap06-resize">). <computeroutput>OrderMgmtView</computeroutput> contains the code specific to the Order Management application. The only reason for splitting the code like this is that it seems to fall happily into these two parts. This reduces the amount @@ -166,7 +167,7 @@ credit-check agency.</para> <para>Finally, it's worth noting that the folder structure, while useful for development, is not necessarily the most appropriate structure for a deployed application. A more - appropriate deployment structure will be described in the next chapter. + appropriate deployment structure will be described in a later chapter. </para> </section> <!-- End of section 6.1.1 --> @@ -190,7 +191,7 @@ which the *.rc file is created. For example, if <computeroutput>CustomerView.rc</computeroutput> is created in the <computeroutput>Customer</computeroutput> folder, then the icon will be specified in <computeroutput>CustomerView.rc</computeroutput> with the path - <computeroutput>".\\bmp\\Customer.ico"</computeroutput> So the path to the icon + <computeroutput>".\\bmp\\Customer.ico"</computeroutput>. So the path to the icon resource in the *.rc file will be wrong, and the dialog icon will not be shown.</para> <para>The solution is either to edit the *.rc file and change the icon resource's path, or (better) create the *.rc file in the Exercise06 folder and then move it into the @@ -206,8 +207,10 @@ from the <computeroutput>Exercise06</computeroutput> folder, since the design decision was taken to make all paths relative to <computeroutput>Exercise06</computeroutput> folder. </para> - <para>This discussion on paths prompts two thoughts (at least). First, is there not a way to have some support code - manage paths, so that each component asks this support code for the path it should use? While this may be feasible, + <para>This discussion on paths prompts two thoughts (at least). + First, is there not a way to have some support code + manage paths, so that each component asks this support code for the path it should use? + While this may be feasible, it's not specifically an ooDialog questions, and so is not pursued here. Second, using the <computeroutput>ResDialog</computeroutput> class instead of <computeroutput>RcDialog</computeroutput> reduces the problem of paths, since resources such as icons and bitmaps are placed in the *.dll file. @@ -215,16 +218,16 @@ </section> <!-- End of Section 6.1.2.1 --> <section><title>.Application Usage</title> <!-- Section 6.1.2.2 --> - <para>The file (<computeroutput>startup.rex</computeroutput>) applies application-wide - defaults with the statement <emphasis role="italic">.Application~setDefaults("O", , .false)</emphasis> . + <para>The <computeroutput>startup.rex</computeroutput> file applies application-wide + defaults through the statement <emphasis role="italic">.Application~setDefaults("O", , .false)</emphasis> . However, the header file for each view class is included at the beginning of its file. For example, <emphasis role="italic">.Application~addToConstDir("Customer\CustomerView.h")</emphasis> is the first - executable statement in the file <computeroutput>CustomerView.rex</computeroutput>. + executable statement in <computeroutput>CustomerView.rex</computeroutput>. For a shipped application that includes multiple classes, it would be much better to provide all the <emphasis role="italic">~addToConstDir()</emphasis> statements in the startup file after, say, the <computeroutput>~setDefaults()</computeroutput> statement. However, because at this stage the application is still in a pre-deployment state, and each component needs to be able to be unit-tested - (see <xref linkend="apx-satesting"/>), + (see <xref linkend="apx-satesting">), it was deemed better to include the <emphasis role="italic">~addToConstDir()</emphasis> statements in each view file. An alternative was to duplicate them in the unit-test startup programs, but code duplication is generally not the best strategy. <indexterm><primary>Unit-testing</primary><secondary>Placement of .Application statement</secondary></indexterm> @@ -239,9 +242,10 @@ distinguish the various HRS classes if the various files were later to be placed into a single file for application deployment purposes. </para> - <para>Human-readable strings in *.rc classes are a problem when internationalization is a requirement. Internationalization - (often referred to as I18N - there are 20 letters in the word "internationalization") is the term given to - providing for translation of human-readable text to other languages. + <para>Human-readable strings in *.rc classes are a problem when internationalization is a requirement. + "Internationalization" + (often referred to as I18N - there are 20 letters in the word) is the term given to + providing for translation of human-readable text into other languages. <indexterm><primary>Internationalization</primary></indexterm> An immediate solution is to display the translated strings from within the program rather than from the *.rc file. The <emphasis role="italic">initDialog</emphasis> method is a good place to do this. Try inserting the following @@ -264,9 +268,10 @@ Some authorities suggest that 150% of the space required for English is needed to allow for proper translations to other languages. And this is only one of the lesser considerations in the task of internationalization. The following quote from the Wikipedia entry illustrates something of the full complexity of I18N: - "It should be noted that "internationalized" does not necessarily mean that a system can be used absolutely anywhere, + "It should be noted that 'internationalized' does not necessarily mean that a system can be used absolutely anywhere, since simultaneous support for all possible locales is both practically almost impossible and commercially very hard - to justify. In many cases an internationalized system includes full support only for the most spoken languages, + to justify. In many cases an internationalized system includes full support + only for the most spoken languages, plus any others of particular relevance to the application." </para> </section> <!-- End of Section 6.1.2.3 --> @@ -298,18 +303,23 @@ <indexterm><primary>Component names</primary><secondary>Naming convention</secondary></indexterm> This convention is useful to differentiate between the various parts of the application. Thus "X Management" is the name given to the application as a whole (in our case "X" is "Sales Order"). - Generally, a componentized application has one or more "coordinator" components that arrange for the + Generally, a componentized application has one or more "coordinator" + or "process" components that arrange for the "choreographing" of other components. These are often called "Managers" - hence the "Order Manager" component that provides the framework for the application. Finally, entities such as Customer are given the entity name - "Customer", "Product", etc. - followed by the suffix "View", "Model", - or "Data" as discussed in <xref linkend="chapThree"/>. + or "Data" as discussed in <xref linkend="chapThree">. + <!-- was <xref linkend="chapThree"/> but the / showed. --> </para> - <para>Finally, starting an application that can make changes to a business is generally guarded by some form of security. - When starting the sample application, this is represented by a password dialog, which is visible if you start the application - (in the <computeroutput>Exercise06</computeroutput> folder) with the command <emphasis role="italic">startup enterPW</emphasis> instead of just - <emphasis role="italic">startup</emphasis>. Yes, this is the wrong way round, but its purpose is to illustrate the code - required for a password prompt. It is very simple, and uses one of the many ooDialog built-in dialogs (documented in the - ooDialog Reference sections 6.2 "Standard Dialog Classes" and 6.3 "Public Routines"), as follows: + <para>Finally, starting an application that can make changes to a business is generally + guarded by some form of security. When starting the sample application, this is represented + by a password dialog, which is visible if you start the application (in the + <computeroutput>Exercise06</computeroutput> folder) with the command + <emphasis role="italic">startup enterPW</emphasis> instead of just + <emphasis role="italic">startup</emphasis>. Yes, this is the wrong way round, + but its purpose is to illustrate the code required for a password prompt. + It is very simple, and uses one of the many ooDialog built-in dialogs - + <computeroutput>PasswordBox(...)</computeroutput>, as follows: <programlisting> <![CDATA[ parse arg pwOption @@ -337,8 +347,8 @@ <indexterm><primary>Parents</primary><secondary>Popups</secondary></indexterm> <para>In previous chapters, dialogs have been started using the statement <emphasis role="italic">self~execute(...)</emphasis>. The <emphasis role="italic">~execute</emphasis> method - makes the dialogs "modal", that is, access to other dialogs is blocked until the dialog is closed - (ooDialog Reference section 2.2.11). A good example of a modal dialog is the Help-About + makes the dialogs "modal", that is, access to other dialogs is blocked until the dialog is closed. + A good example of a modal dialog is the Help-About dialog in Exercise 5. While this is open, the Product View dialog is blocked. </para> <para>The dialogs in Exercise 6 are not modal; they are "amodal" or "modeless". Any of them can be accessed @@ -363,46 +373,48 @@ <indexterm><primary>PopupAsChild</primary></indexterm> </para> <para> - It is the latter - <emphasis role="italic">~popupAsChild</emphasis> - + It's <emphasis role="italic">~popupAsChild</emphasis> that best fits the requirements of the Order Management application. Thus while - <computeroutput>OrderMgrView</computeroutput> is started with <emphasis role="italic" - >~execute</emphasis>, all other Order Management dialogs are started with <emphasis - role="italic">~popupAsChild(rootDlg)</emphasis> where the "root" (or parent) dialog is always - <computeroutput>OrderMgrView</computeroutput>. Thus all dialogs are modeless and independent of each other. + <computeroutput>OrderMgrView</computeroutput> is started with + <emphasis role="italic">~execute</emphasis>, all other Order Management dialogs + are started with <emphasis role="italic">~popupAsChild(rootDlg)</emphasis> + where the "root" (or parent) dialog is always + <computeroutput>OrderMgrView</computeroutput>. So all dialogs are modeless + and independent of each other. The application ends only when <computeroutput>OrderMgrView</computeroutput> is closed. (Note that <computeroutput>ProductView</computeroutput>'s "About" dialog is still modal: it blocks access to the specific instance of <computeroutput>ProductView</computeroutput> from which it is launched; other instances of <computeroutput>ProductView</computeroutput> are unaffected, as are other dialogs.) </para> <para>So, for a dialog to be "popped up as child", there has to be a parent dialog that was - surfaced with either <emphasis role="italic">~popup</emphasis> or <emphasis role="italic" - >~execute</emphasis>. This presents a problem for stand-alone testing. The solution - adopted in the sample Order Management application is illustrated in the following code - fragment, taken from <computeroutput>CustomerListView</computeroutput>'s <emphasis - role="italic">activate></emphasis> method (which is called from its <emphasis - role="italic">newInstance</emphasis> class method): <programlisting> + surfaced with either <emphasis role="italic">~popup</emphasis> or + <emphasis role="italic">~execute</emphasis>. This presents a problem for stand-alone testing. + The solution adopted in the sample Order Management application is illustrated + in the following code fragment, taken from <computeroutput>CustomerListView</computeroutput>'s + <emphasis role="italic">activate</emphasis> method (which is called from its + <emphasis role="italic">newInstance</emphasis> class method): <programlisting> <![CDATA[ ::METHOD activate UNGUARDED expose rootDlg use arg rootDlg if rootDlg = "SA" then do -- If standalone operation required - rootDlg = self -- To pass on to children + rootDlg = self -- To pass on to children self~execute("SHOWTOP","IDI_CUSTLIST_DLGICON") end else self~popupAsChild(rootDlg, "SHOWTOP", ,"IDI_CUSTLIST_DLGICON") return ]]> </programlisting>This code illustrates the two ways of starting a dialog. For - stand-alone testing (see <xref linkend="apx-satesting"/>), the dialog is started using + stand-alone testing (see <xref linkend="apx-satesting">), the dialog is started using <emphasis role="italic">self~execute()</emphasis>. In normal operation, however, it is started by <emphasis role="italic">self~popupAsChild(...)</emphasis>. Notice that the first parameter of <emphasis role="italic">~popupAsChild(rootDlg, ...)</emphasis> is the <computeroutput>OrderMgrView</computeroutput> dialog, which is passed to the <emphasis role="italic">newInstance</emphasis> class method and thence as the parameter <emphasis role="italic">rootDlg</emphasis> to the <emphasis role="italic">activate</emphasis> - method. This dialog, the <computeroutput>CustomerListView</computeroutput> class, is both - a child of the <computeroutput>OrderMgr</computeroutput> and parent of the - <computeroutput>Customer</computeroutput> class. Later in + method. Thus <computeroutput>CustomerListView</computeroutput> is both + a child of <computeroutput>OrderMgr</computeroutput> and parent of + <computeroutput>Customer</computeroutput>. Later in <computeroutput>CustomerListView</computeroutput>, a Customer is displayed by the user double-clicking on an item in the List View. The event handler method (<emphasis role="italic">showCustomer</emphasis>) that surfaces the Customer is as follows: @@ -418,7 +430,7 @@ info=.Directory~new if lvCustomers~getItemInfo(item, info) then do .local~my.idCustomerData = .CustomerData~new -- create Customer Data instance - .local~my.idCustomerModel = .CustomerModel~new -- create Customer Model instance + .local~my.idCustomerModel = .CustomerModel~new -- create Customer Model instance .local~my.idCustomerData~activate .local~my.idCustomerModel~activate .CustomerView~newInstance(rootDlg,"CU003") @@ -429,22 +441,21 @@ end ]]> </programlisting> - The list of customers is shown in a ListView control (see <link linkend="lviews.title">Icons and Lists</link> below). + The list of customers is shown in a ListView control + (see <link linkend="chap06-lviews" endterm="lviews.title"></link> below). The <emphasis role="italic">showCustomer</emphasis> - method is invoked when the user double-clicks on an item in the list. This item is - identified by the statement <emphasis role="italic">item = - lvCustomers~selected</emphasis>, the proxy object for the list control being <emphasis - role="italic">lvCustomers</emphasis>. If no item is selected, an error message is - displayed, and the method returns. The data in the selected row is then placed in a - directory (with an error check in case <emphasis role="italic">~getItemInfo</emphasis> - returns <computeroutput>.false</computeroutput>). The next statements (<emphasis - role="italic">.local~my...</emphasis>) create instances of the - <computeroutput>CustomerModel</computeroutput> and - <computeroutput>CustomerData</computeroutput> classes that are required by - <computeroutput>CustomerView</computeroutput> (see <link linkend="chap03-cplg">Reducing - Coupling</link>. Then - an instance of <computeroutput>CustomerView</computeroutput> is created by the statement - <emphasis role="italic">.CustomerView~newInstance(rootDlg,"CU003")</emphasis>. The second + method is invoked when the user double-clicks on an item in the list. This item is + identified by the statement <emphasis role="italic">item = + lvCustomers~selected</emphasis>, the proxy object for the list control being <emphasis + role="italic">lvCustomers</emphasis>. If no item is selected, an error message is + displayed, and the method returns. The data in the selected row is then placed in a + directory (with an error check in case <emphasis role="italic">~getItemInfo</emphasis> + returns <computeroutput>.false</computeroutput>). The next statements (<emphasis + role="italic">.local~my...</emphasis>) create instances of the + <computeroutput>CustomerModel</computeroutput> and + <computeroutput>CustomerData</computeroutput> classes. Then + an instance of <computeroutput>CustomerView</computeroutput> is created by the statement + <emphasis role="italic">.CustomerView~newInstance(rootDlg,"CU003")</emphasis>. The second parameter is the Customer Number, which is ignored in Exercise 6 (but which will be used in Exercise 7). Finally, the "Show Customer" pushbutton is disabled. </para> <para> @@ -470,8 +481,8 @@ <para> However, ooDialog also provides a half-way house, where simple code produces a useful result. This simpler code, which will be used in Exercise 7, is discussed in - <xref linkend="apx-satesting"/>, section <link linkend="apx-satesting-offsets" endterm="offsetting.title"></link>. - The following code illustrates the key functions: + <link linkend="apx-satesting-offsets" endterm="offsetting.title"></link> in + <xref linkend="apx-satesting">. The following code illustrates the key functions: <programlisting> <![CDATA[ -- In 'parent' dialog: @@ -506,7 +517,7 @@ <para>When an icon in the Order Management dialog is double-clicked, a child dialog is surfaced. This is handled by two methods in the <computeroutput>OrderMgrView</computeroutput> class. First, the event-handling method <emphasis>onDoubleClick</emphasis> catches the - double-click, works out which icon (or "record" - see <xref linkend="chap06-lviews"/> + double-click, works out which icon (or "record" - see <xref linkend="chap06-lviews"> below) was double-clicked, and then calls the <emphasis role="italic">showModel</emphasis> method. This method uses an <emphasis role="italic">interpret</emphasis> instruction to launch a view of the component represented by chosen icon, as follows: <programlisting> @@ -557,20 +568,15 @@ </itemizedlist> </para> <para>In the Order Management application, a ListView control in the "icon" style provides the main area - of the Order Management dialog where draggable icons represent the various components of the application. + of the <computeroutput>OrderManager</computeroutput> dialog where draggable icons + represent the various components of the application. The ListView control in the "report" style is used to provide the tabular lists for - <computeroutput>CustomerList</computeroutput>, + <computeroutput>CustomerListView</computeroutput>, <computeroutput>ProductListView</computeroutput>, and <computeroutput>OrderListView</computeroutput> dialogs. Indeed, the code in these three dialogs is extremely similar, suggesting that a superclass could be useful. </para> <section id="chap06-lviews-icon"><title>The Icon View</title> <!-- Section 6.3.1 --> - <!-- - 6.3.1 The Icon View - - List Views - normal icon view - a "workplace" for Order Management.. - - Auto-resizing when window sized by user - --> - <para> The Order Management dialog is provided by two classes: <computeroutput>OrderMgrBaseView</computeroutput> and <computeroutput>OrderMgrView</computeroutput>. The former handles re-sizing, and to do this it needs @@ -594,7 +600,7 @@ and there are a number of differences between them. The bitmaps themselves are in the folders of the relevant business components, so the "icon" for the Customer List, for example, is <computeroutput>Exercise06\Customer\bmp\CustList.bmp</computeroutput> (the - <computeroutput>*.ico</computeroutput> files are the dialog icons). See <xref linkend="chap06-icons"/> + <computeroutput>*.ico</computeroutput> files are the dialog icons). See <xref linkend="chap06-icons"> for further information. </para> </listitem> @@ -605,9 +611,9 @@ <computeroutput>LVS_ICON</computeroutput> (in ResEdit, set the "View" property to "Icon"), or in a UserDialog, by creating the ListView control in the <emphasis role="italic">initDialog</emphasis> method using the - <computeroutput>ICON</computeroutput> style (e.g.: + <computeroutput>ICON</computeroutput> style - e.g.: <computeroutput>self~createListView(IDC_ORDMGMT_ICONS, ... "ICON")</computeroutput> - where the first parameter is the ID for the ListView control.). </para> + where the first parameter is the ID for the ListView control. </para> </listitem> <listitem> <!-- 3 --> @@ -647,7 +653,7 @@ <para><emphasis role="bold"><emphasis role="italic">Create Records</emphasis></emphasis></para> <para>Records are typically created in the <emphasis role="italic">init</emphasis> method (or in a method invoked from there). In <computeroutput>OrderMgrView</computeroutput> the records are created in the - <emphasis role="italic">initRecords</emphasis>) method which is invoked from + <emphasis role="italic">initRecords</emphasis> method which is invoked from <emphasis role="italic">init</emphasis>. Each record has two fields: the class name of the dialog to be surfaced when a user double-clicks on an icon, and the text to appear beneath the icon. The design choice for these records is that each record is a directory, and each directory is to be @@ -657,15 +663,15 @@ <programlisting> <![CDATA[ ::METHOD initRecords PRIVATE - expose records - records = .array~new() - ... - rec = .directory~new - rec~ID = "OrderList" -- Class Name - rec~name = "Sales Orders" -- Text to display under the icon - records[3] = rec - ... - return records + expose records + records = .array~new() + ... + rec = .directory~new + rec~ID = "OrderList" -- Class Name + rec~name = "Sales Orders" -- Text to display under the icon + records[3] = rec + ... + return records ]]> </programlisting> </para> @@ -674,7 +680,7 @@ <para><emphasis role="bold">Load the ImageList and the Records</emphasis></para> <para>Loading icon images and records into the ListView is done in <computeroutput>OrderMgrView</computeroutput>'s - <emphasis role="italic">initDialog</emphasis>method: + <emphasis role="italic">initDialog</emphasis> method: <programlisting> <![CDATA[ ::METHOD initDialog @@ -687,17 +693,18 @@ ]]> </programlisting> After invoking the superclass, the icons in the ImageList are all applied to the ListView control in the - single statement, <emphasis role="italic">self~lv~setImageList(..)</emphasis>. The second parameter of + single statement, <emphasis role="italic">self~lv~setImageList(..)</emphasis>. + The second parameter of the <emphasis role="italic">setImageList</emphasis> method specifies the size of the icons by invoking - the Image class' <emphasis role="italic">toID</emphasis> method with the parameter - <emphasis role="italic">LVSIL_NORMAL</emphasis> which is the flag for the icon view as opposed to - the list, report, and small icon views. The Image class is used to work with and manipulate images. + the <emphasis role="italic">toID</emphasis> method of the Image class with the parameter + <emphasis role="italic">LVSIL_NORMAL</emphasis>. This is the flag for the icon view as opposed to + the list, report, or small icon views. The Image class is used to work with and manipulate images. The variable <emphasis role="italic">self~lv</emphasis> is the list view proxy, <emphasis role="italic">lv</emphasis> being an attribute of the <computeroutput>OrderMgrBaseView</computeroutput> superclass. The icons having been set, the records are then added using the ListView's <emphasis role="italic">addRow</emphasis> method. The first parameter is the index of the list - item - if omitted, the record is added after the last. The second parameter is the index of the icon to + item; if omitted, the record is added after the last. The second parameter is the index of the icon to be used with this record, and the last parameter is the label for the list item - the string "Customer List" in the case of the first item added. </para> @@ -782,9 +789,10 @@ The <emphasis role="italic">~addRow</emphasis> method adds a row of data into the list view. As can be seen, the data in the list is hard-coded. This will be fixed in Exercise 7. The first parameter is the 0-based index of the item, and defaults to the index of the last item added plus 1 (if no items - already in the list view, this defaults to 0). Note however that the last item appears first not last. - This is because the *.rc file has the style <computeroutput>LVS_SORTASCENDING</computeroutput>. - The second parameter is the index (in an ImageList) of the iter's icon should that be required. + already in the list view, this defaults to 0). Note however that when the user + creates the dialog, the last item appears first not last. + This is because the *.rc file specifies the style <computeroutput>LVS_SORTASCENDING</computeroutput>. + The second parameter is the index (in an ImageList) of the item's icon should that be required. Finally, the last statement sets the width of the second column to that of the longest text entry. Note that loading the list view with data could have been done in the <emphasis role="italic">initDialog</emphasis> method. However, the separation of concerns principle @@ -822,7 +830,7 @@ ]]> </programlisting> In the first approach, If the user double-clicks on a row, and the row is empty, the second - click of the double-click is ignored, else the double-click method (<emphasis role="italic">openItem</emphasis> + click of the double-click is ignored, else the double-click method (<emphasis role="italic">openItem</emphasis>) is invoked. This is turn invokes <emphasis role="italic">showCustomer</emphasis>. In the second approach, the <emphasis role="italic">itemSelected</emphasis> method is fired when the user clicks on a row in the ListView. If the user clicks on an empty row, then @@ -868,7 +876,7 @@ - unlike the size of the List View - does not change. This re-sizing function is only available for a <computeroutput>UserDialog</computeroutput>, and requires a number of methods and lines of code. ooDialog provides three samples of the resizing function in the folder - <computeroutput>ooRexx\samples\oodialog</computeroutput> folder - + <computeroutput>ooRexx\samples\oodialog</computeroutput>, the relevant programs being <computeroutput>dlgAreaUDemo.rex</computeroutput>, <computeroutput>dlgAreaUDemoTwo.rex</computeroutput>, and <computeroutput>dlgAreaUDemoThree.rex</computeroutput>. @@ -890,7 +898,7 @@ <para>This section discusses first the creation of icons and bitmaps, and secondly how the icons in the Order Management dialog are loaded into its icon-style List view.</para> <para>Various questions arise when creating icons for the first time - especially since the - whole area of images in Windows is not, on first glance, simple. + whole area of images in Windows is not, at first glance, simple. This section lists some of the main points about creating icons.</para> <para>First, it's important to establish whether what's required is an icon (file type .ico) or a bitmap (file type *.bmp). The "icons" in the Order Management dialog are actually bitmaps. But a @@ -971,7 +979,7 @@ (e.g. "ProductList") of the component to be launched when the user double-clicks an icon. </para> <para>Finally, in the <emphasis role="italic">initDialog</emphasis> method, the image list - (<emphasis role="italic">lv</emphasis>) is first set into (added to) the list view, follwoing which + (<emphasis role="italic">lv</emphasis>) is first set into (added to) the list view, following which the records are added. It is a user responsibility to make sure the sequence of icons in the icon list matches the sequence of text data in the records array. </para> @@ -994,8 +1002,8 @@ say "OrderMgrView-showModel-02:" ]]> </programlisting> - The <emphasis role="italic">onDoubleClick</emphasis> is the event handler method defined for the list view, and - is defined in the <computeroutput>OrderMgrBaseView</computeroutput> superclass. The first statement (after + The <emphasis role="italic">onDoubleClick</emphasis> method is the event handler method defined for the list view, and + is specified in the <computeroutput>OrderMgrBaseView</computeroutput> superclass. The first statement (after <emphasis role="italic">expose records</emphasis>) finds which icon has focus - that is, which was double-clicked. The second retrieves the corresponding record, and then <emphasis>showModel</emphasis> is invoked with the appropriate record. In <emphasis>showModel</emphasis> an appropriate view is created and surfaced using the @@ -1007,14 +1015,14 @@ each of Customers, Products and Orders will be allowed. When the user double-clicks on an icon, the appropriate list will be "surfaced" in the proper sense of the word - that is, created and shown as the top-level dialog, or, if already created, will have focus put on it so that, if hidden under other - dialogs, will pop to the "surface" - that is, become the topmost window on the screen.</para> + dialogs, it will pop to the "surface" - that is, become the topmost window on the screen.</para> </section> <!-- End of section 6.5 --> <section id="chap06-utildlgs"><title id="utildlgs.title">Utility Dialogs</title> <!-- Section 6.6 --> <indexterm><primary>Password dialog</primary></indexterm> <indexterm><primary>Utility routine</primary><secondary>PasswordBox</secondary></indexterm> - <para>A subject not yet mentioned is the use of ooDialog utility classes and routines in non-ooDialog ooRexx programs. - These are documented in Chapter 25 of the ooDialog Reference. The routines are very simple, and are often one-liners. + <para>A subject not yet mentioned is the use of ooDialog utility classes and routines + in non-ooDialog ooRexx programs. The routines are very simple, and are often one-liners. As an example, the Exercise 6 startup program provides for entry of a password using the (one-line) <computeroutput>PasswordBox</computeroutput> routine. Invoking <emphasis role="italic">startup enterPW</emphasis> produces a password box that will accept the password This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-05-20 22:30:44
|
Revision: 7798 http://oorexx.svn.sourceforge.net/oorexx/?rev=7798&view=rev Author: osims Date: 2012-05-20 22:30:37 +0000 (Sun, 20 May 2012) Log Message: ----------- Deleted Appendix 1 (and removed ref to it in Chapter 4). Also a minor mode to Chapter 4 removing reference to Appendix 1, and adding sentence about event-handler methods having to be PUBLIC. Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/oodguide.xml Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-05-16 15:55:42 UTC (rev 7797) +++ docs/trunk/oodguide/Chapter04.xml 2012-05-20 22:30:37 UTC (rev 7798) @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter04 - Using Resource Dialogs v00-12 10Apr12 +<!-- Chapter04 - Using Resource Dialogs v00-13 20May12 4.1 Naming and Coding Conventions 4.1.1 Naming Conventions 4.1.2 Coding Conventions @@ -60,6 +60,9 @@ v00-10 01Apr12: Corrected text about create menubar (last param now not there). v00-11 02Apr12: Minor mods after seeing the PDF. v00-12 10Apr12: Tag corrected by M. Miesfeld. + v00-13 20May12: Took out ref to appendix about Connections (this + well-covered now in the ooDialog Reference). Added some text + about event handlers having to be Public methods. --> <chapter id="chapFour"> <title>Using Resource Dialogs</title> @@ -488,6 +491,7 @@ self~connectButtonEvent("IDC_CUST_BTN_RECORDCHANGES","CLICKED",recordChanges) ]]> </programlisting>This is an example of specifying an "event handler" (inbound active behavior). + <indexerm><primary>Event handler</primary></indexerm> Suppose the user presses the "Record Changes" button. The Windows runtime signals the event, which ooDialog picks up. The above statement declares that this event - i.e.that the pushbutton identified in the <computeroutput>.h</computeroutput> file as @@ -502,7 +506,10 @@ <computeroutput>UNGUARDED</computeroutput>. In general, an event handler should be unguarded to preclude the possibility that some guarded method in the dialog object is executing at the time the event notification is generated. For further information, see - the ooDialog Reference. + the ooDialog Reference. Note also that event-handling methods must be PUBLIC, + since they are invoked from outside the ooRexx dialog class by the underlying + ooDialog code (and of course an ooRexx method is public unless PRIVATE is specified). + <indexerm><primary>Event handler</primary><secondary>Public method</secondary></indexerm> <indexterm><primary>Unguarded method</primary></indexterm></para> <para>Specification of active controls is generally done in the <emphasis role="italic" >initDialog</emphasis> method. Indeed, in the @@ -510,7 +517,8 @@ occupies most of this method. </para> <para> Note that menubar actions are not specified. This is because the menu items in <computeroutput>CustomerView.rex</computeroutput> are "auto-connected" (see - <link linkend="apx-connections" endterm="connections.title"></link>). Auto-connection is specified + "Menu Command Event Connections" in the ooDialog Reference). + Auto-connection is specified in the last parameter of the following <emphasis role="italic">.ScriptMenuBar~new</emphasis> statement in the <emphasis role="italic">createMenuBar</emphasis> method: <indexterm<primary>Autoconnection</primary></indexterm> Modified: docs/trunk/oodguide/oodguide.xml =================================================================== --- docs/trunk/oodguide/oodguide.xml 2012-05-16 15:55:42 UTC (rev 7797) +++ docs/trunk/oodguide/oodguide.xml 2012-05-20 22:30:37 UTC (rev 7798) @@ -8,7 +8,6 @@ <!ENTITY chapter4 SYSTEM "Chapter04.xml"> <!ENTITY chapter5 SYSTEM "Chapter05.xml"> <!ENTITY chapter6 SYSTEM "Chapter06.xml"> -<!ENTITY appendix01 SYSTEM "appendix01.xml"> <!ENTITY appendix02 SYSTEM "appendix02.xml"> <!ENTITY appendix03 SYSTEM "appendix03.xml"> <!ENTITY appendix04 SYSTEM "appendix04.xml"> @@ -58,12 +57,14 @@ ######################################################################### --> -<!-- Book. v00-02 23Apr12 +<!-- Book. v00-03 20May12 Changes: v00-01: First version v00-02 23Apr12: Deleted Appendix 1 "Connections" - was note-form only and info is now ooDialog Reference so redundant here. + v00-03 20May12: Delete Appendix 1 "Connections" (not properly deleted + before 'cos refence was not also deleted). --> <book> @@ -85,7 +86,7 @@ &chapter5; <!-- Fifth chapter --> &chapter6; <!-- Sixth chapter --> <!-- start of appendix --> -&appendix01; <!-- First appendix --> +<!-- &appendix01; --> &appendix02; <!-- Second appendix --> &appendix03; <!-- Third appendix --> &appendix04; <!-- Fourth appendix --> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-05-31 16:49:28
|
Revision: 7818 http://oorexx.svn.sourceforge.net/oorexx/?rev=7818&view=rev Author: osims Date: 2012-05-31 16:49:21 +0000 (Thu, 31 May 2012) Log Message: ----------- Final check and polish for Chaps 2 and 3. Modified Paths: -------------- docs/trunk/oodguide/Chapter02.xml docs/trunk/oodguide/Chapter03.xml Removed Paths: ------------- docs/trunk/oodguide/appendix01.xml Modified: docs/trunk/oodguide/Chapter02.xml =================================================================== --- docs/trunk/oodguide/Chapter02.xml 2012-05-31 04:09:25 UTC (rev 7817) +++ docs/trunk/oodguide/Chapter02.xml 2012-05-31 16:49:21 UTC (rev 7818) @@ -38,13 +38,10 @@ ######################################################################### --> -<!-- Chapter02 - In The Beginning v00-08 02Apr12 - v00-04 26Jly11 - v00-05 11Aug11: Minor corrections to match exercise numbers. - v00-06 06Feb12: Code change - resource number -1 changed to 101. - v00-07 31Mar12: Correction to role=italic (no quotes). - v00-08 02Apr12: Add para on windows vs dialogs; change all uses of "window" - to "dialog". +<!-- Chapter02 - In The Beginning v01-00 31May12 + + Changes: + v01-00 31May12: First version. --> <chapter id="chapTwo"><title>In The Beginning</title> @@ -56,7 +53,7 @@ boxes, and so forth. The user keys data into controls (e.g. types into an edit control) or manipulates controls with a mouse (e.g. selects an item in a listbox). Some of these actions invoke application code which in turn - makes some change to the window or dialog, causes some other action such as + makes some change to the window or dialog, or causes some other action such as data access, or both. </para> <para> @@ -65,11 +62,11 @@ have evolved they have become more useful, and can now provide the user interface function for many applications. Also, a dialog is drawn by the operating system, while drawing a normal window is mostly the programmer's responsibility. Thus -producing an application needs much less programming work because the Rexx +producing an application needs much less programming work because the ooRexx programmer doesn't need to know or understand the low-level mechanics of drawing to the screen. In summary, dialogs now have many window functions, and are much easier to produce. And it's this that makes ooDialog a particularly useful -extension to a Rexx interpreter. +extension to ooRexx. </para> <para> There are three general areas of concern in designing an ooDialog application: @@ -101,15 +98,17 @@ ensure that your installation works properly. </para> <para><emphasis role="bold"><emphasis role="italic">And please do use the - ooDialog Reference manual for the details on any ooDialog class, method + ooDialog Reference for details on any ooDialog class, method or function mentioned in this Guide.</emphasis></emphasis> </para> <section id="sctGettingStarted"><title>Getting Started</title> <para> The first exercise creates and displays a blank dialog with the title "Hello World!". - Try running it - it's the file <computeroutput>HelloWorld.rex</computeroutput> in - the <computeroutput>Exercises\Exercise02</computeroutput> folder (exercise folder - numbers map to chapter numbers). <xref linkend="fig01"> shows what you should see. + Try running it - it's the file <computeroutput>HelloWorld.rex</computeroutput> in the folder + <computeroutput>C:\Program Files\ooRexx\samples\oodialog\userGuide\exercises\Exercise02</computeroutput> + (exercise numbers map to chapter numbers). <xref linkend="fig01"> shows what you should see. + <indexterm><primary>Exercise location</primary></indexterm> + <indexterm><primary>Location</primary><secondary>of Exercises></secondary></indexterm> </para> <para> The Command Prompt window that appears with the <emphasis role="italic">Hello World</emphasis> @@ -139,10 +138,10 @@ The second statement invokes the <emphasis role="italic">execute</emphasis> method of <computeroutput>HelloWorld</computeroutput>, and it is this that displays the dialog. The first parameter <emphasis role="italic">SHOWTOP</emphasis> is one of several ways of defining - how the dialog is surfaced (see the ooDialog reference for details). + how the dialog is surfaced (see the ooDialog Reference for details). The second parameter states that the icon at the extreme top left of the dialog should be the normal ooRexx icon. This graphic is termed a "resource" in ooDialog, and there are a number - of such predefined constants (again, see the ooDialog reference for details). + of such predefined constants (again, see the ooDialog Reference for details). </para> <para> Note that the usual naming conventions are observed: upper camel case for classes @@ -156,7 +155,7 @@ ::REQUIRES "ooDialog.cls" ]]> </programlisting> - This one directive allows all the classes defined by ooDialog to be accessible to our program. + This directive allows all the classes defined by ooDialog to be accessible to our program. If this statement is absent, then the following error appears on the initiating command prompt: <programlisting> <![CDATA[ @@ -170,8 +169,6 @@ This is because the <emphasis role="italic">::requires ooDialog.cls</emphasis> statement not only says we're using ooDialog, but also provides access to all the classes provided <emphasis role="italic">by</emphasis> ooDialog. - Later, we'll see a further use - for the <emphasis role="italic">::requires</emphasis> directive. </para> <para> Finally, there's the definition of the class <computeroutput>HelloWorld</computeroutput>: @@ -185,7 +182,7 @@ </programlisting> The first line defines a class called <computeroutput>HelloWorld</computeroutput> as a subclass of the ooDialog-provided class <computeroutput>UserDialog</computeroutput> - (and yet again but finally, see the ooDialog Reference for full details). + (and yet again, but finally, see the ooDialog Reference for full details). Among other things, <computeroutput>UserDialog</computeroutput> enables the programmer to define the dialog layout in code. This can get cumbersome in more complex dialogs, and later we'll meet a simpler way of defining the dialog layout. @@ -223,8 +220,8 @@ parameter (and its preceding comma of course) and see what happens. Then replace the <computeroutput>CENTER</computeroutput> parameter, and (just to make sure that you've replaced it correctly) run the program again, - and this time try to size the dialog. You can't. Then replace - <computeroutput>CENTER</computeroutput> by <computeroutput>CENTER THICKFRAME</computeroutput> + and this time try to re-size the dialog. You can't. Then replace + <computeroutput>"CENTER"</computeroutput> by <computeroutput>"CENTER THICKFRAME"</computeroutput> and re-run the program. The dialog now has a sizable border. Thus styles not only affect appearance, they can also define behavior. </para></listitem> @@ -264,7 +261,7 @@ </para> <para> Now let's look at the code. - The first seven lines (excluding comments) + The first seven lines (excluding comments and blank lines) are essentially the same as the first seven in <computeroutput>HelloWorld.rex</computeroutput>: <programlisting> <![CDATA[ @@ -366,7 +363,7 @@ And, since a pushbutton control provides for just such an approach, that's what we'll do here. The first lines of code in <computeroutput>Wow2.rex</computeroutput> - down to the <emphasis role="italic">defineDialog</emphasis> method - are almost identical to those of - <computeroutput>wow.rex</computeroutput>, with only one significant change. + <computeroutput>wow.rex</computeroutput>, with two significant changes. The method is as follows: <programlisting> <![CDATA[ @@ -378,8 +375,8 @@ </programlisting> </para> <para> - There are two significant changes. Firstly, the statement - - <emphasis role="italic">self~createPushButton</emphasis> - + The two significant changes are as follows. Firstly, the statement + <emphasis role="italic">self~createPushButton</emphasis> has an additional parameter <emphasis role="italic">okClicked</emphasis>. This is the name of the method that is automatically invoked by ooDialog when the user clicks on the <emphasis role="italic">More wisdom</emphasis> pushbutton. Secondly, @@ -418,7 +415,8 @@ And this is arguably the most important thing for any application - especially one with a GUI. There are three important areas of design concern - UI display and interaction, the "business" that the dialog performs (here the business of selecting the text), - and the provision of persistent data. But we'll start to fix this in the next chapter. + and the provision of persistent data (here the seven strings comprising the "words of wisdom"). + But we'll start to fix this in the next chapter. </para> </section> Modified: docs/trunk/oodguide/Chapter03.xml =================================================================== --- docs/trunk/oodguide/Chapter03.xml 2012-05-31 04:09:25 UTC (rev 7817) +++ docs/trunk/oodguide/Chapter03.xml 2012-05-31 16:49:21 UTC (rev 7818) @@ -38,16 +38,13 @@ ######################################################################### --> -<!-- Chapter03 - Re-Structuring the Code v00-07 21Apr12 +<!-- Chapter03 - Re-Structuring the Code v01-00 31May12 - v00-04 12Aug11: Changed names of rex files and view classes in the code; - text changed to match, plus some minor corrections. - v00-05 02Apr12: Minor corrections. - v00-06 21Apr12: Change book ref. Also add stuff on "components". - v00-07 21Apr12: Added a title link ("reduce-cplg") + Changes: + v01-00 31May12: First version. --> <chapter id="chapThree"><title>Re-Structuring the Code</title> -<indexterm><primary>code structure</primary></indexterm> +<indexterm><primary>Code structure</primary></indexterm> <para>The current code is not good. It works - but only because it's very simple. The problem is its design - its structure. There are three quite different concerns which, for all but he simplest of programs, should be separated. These are: the @@ -94,8 +91,8 @@ probably be another kind of Model component which in turn would use a separate Data component that accesses a corporate database or remote service).</para> <para>But why use the term "component" instead of "class"? The answer is (as will be seen in later - exercises) that for industrial-strength apps, a component always consists of a number of - classes. And a single class cannot be independently "plugged in" to a runtime environment + exercises) that for industrial-strength apps, a component generally consists of a number of + classes. And a single class can seldom be independently "plugged in" to a runtime environment without the other classes required fully to implement a single business concept in its View, Model or Data role. A component, however, is intended to be "pluggable" into the runtime, since it is all and only the implementation of one of the "view", "model", or "data" aspect of @@ -145,7 +142,7 @@ method is identical to that of Exercise02's <computeroutput>Wow2</computeroutput> except that it also creates an instance of <computeroutput>WowPicker</computeroutput> called (unsurprisingly) <emphasis - role="italic">wowPicker</emphasis>". There's also an + role="italic">wowPicker</emphasis>. There's also an <emphasis role="italic">expose</emphasis> statement to make the <emphasis role="italic">wowPicker</emphasis> object available to other methods. </para> @@ -167,9 +164,9 @@ <para>One other change is that instead of creating a new static text control every time the button is pressed, the control is created once in the new <emphasis role="italic" >initDialog</emphasis> method and re-used in the <emphasis role="italic" - >okClicked"</emphasis> method. The <emphasis role="italic">initDialog</emphasis> method + >okClicked</emphasis> method. The <emphasis role="italic">initDialog</emphasis> method is called automatically by ooDialog after the dialog has been created in order to allow - controls to be initialized.</para> + controls to be initialized (the "init" in "initDialog" stands for "initialize").</para> <para>In summary, all knowledge of picking a string, and of the set from which to pick, has been exported elsewhere. The <computeroutput>WowView</computeroutput> class now addresses only the areas of GUI display and GUI interaction. This is crucially important. A good way to @@ -183,22 +180,22 @@ - is very simple: <programlisting> <![CDATA[ ::METHOD init - expose arrWowSet + expose wowSet dataSource = .WowData~new - arrWowSet = dataSource~readWowSet + wowSet = dataSource~readWowSet return ::METHOD pickWow - expose arrWowSet + expose wowSet i = random(1,7) - return arrWowSet[i] + return wowSet[i] ]]> </programlisting>The <emphasis role="italic">init</emphasis>method gets a reference to an instance of the class <computeroutput>WowData</computeroutput> - which handles the data area of concern - and then gets a set of Words of Wisdom into the array variable <emphasis - role="italic">arrWowSet</emphasis>. Then in the method <emphasis role="italic" + role="italic">wowSet</emphasis>. Then in the method <emphasis role="italic" >pickWow</emphasis> a Words of Wisdom string is picked randomly from <emphasis - role="italic">arrWowSet</emphasis> and returned. </para> + role="italic">wowSet</emphasis> and returned. </para> </section> <section id="chap03-struc-dat"><title>The "Data" Component</title><!-- section 3.1.3 --> @@ -294,7 +291,7 @@ when the dialog is closed (although, as will be discussed later, there are ways to return control much sooner). </para> - <para>But why move the <emphasis role="italic">self~execute("SHOWTOP"...</emphasis> statement into + <para>But why move the <emphasis role="italic">self~execute("SHOWTOP"...)</emphasis> statement into the <emphasis role="italic">activate</emphasis> method of the <computeroutput>MyDialog</computeroutput> class? After all, it would work just as well if it were the last statement in the Startup file. The reason is that the business of surfacing @@ -313,12 +310,15 @@ >okClicked</emphasis> method can not run until the <emphasis role="italic" >activate</emphasis> method ends - that is, until the user closes the dialog window - a real catch 22, where the result is that no words of wisdom will appear. </para> + <indexterm><primary>Concurrency issue</primary></indexterm> + <indexterm><primary>Blocking</primary><secondary>concurrency issue</secondary></indexterm> <para> The reason <computeroutput>WowView</computeroutput> works is because its <emphasis role="italic">activate</emphasis> method has the <emphasis role="italic">unguarded</emphasis> option specified on its method statement. Try commenting "UNGUARDED" out and running the exercise without it. </para> + <indexterm><primary>Unguarded</primary></indexterm> <para> As a general rule, event handling methods such as <emphasis role="italic">okClicked</emphasis> should be unguarded. Indeed, <computeroutput>WowView</computeroutput> runs happily if the "unguarded" option is moved to the <emphasis role="italic">okClicked</emphasis> method statement - or Deleted: docs/trunk/oodguide/appendix01.xml =================================================================== --- docs/trunk/oodguide/appendix01.xml 2012-05-31 04:09:25 UTC (rev 7817) +++ docs/trunk/oodguide/appendix01.xml 2012-05-31 16:49:21 UTC (rev 7818) @@ -1,274 +0,0 @@ -<!--######################################################################### - # - # Description: Open Object Rexx: ooDialog User Guide XML file. - # - # Copyright (c) 2011-2012 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 01 version 00-01 - Connections (??title??) - This is all about connections between menus and buttons with programs. ---> -<appendix id="apx-connections"><title id="connections.title">Connections</title> -<indexterm><primary>Connections</primary></indexterm> - -<para> - This appendix discusses the various ways in which events published by menu items - and pushbuttons can be connected to the ooRexx program. -</para> -<para> - <emphasis role='bold'>Note: This appendix is in initial note form taken from several sources - it has yet to be - merged, completed, checked, and properly marked up.</emphasis> -</para> - -<section id="app01-menus"><title>Connecting Menu Command Items to Dialog Methods</title> -<para> -There are basically three ways to connect menu command items to a dialog: -<itemizedlist> - <listitem><para>autoConnection</para></listitem> - <listitem><para>connection request</para></listitem> - <listitem><para>directly connect</para></listitem> -</itemizedlist> -In general the three ways should not be mixed without without using some -forethought. Autoconnection should never be used with the other two. -Mixing the three ways of connecting command items to methods can result in -unpredicatable results: -<itemizedlist> - <listitem><para> - The same command item can end up connected to different methods, which - method is invoked is non-deterministic.</para></listitem> - <listitem><para>Numerous entries for the same command item connected to the same method - can happen.</para></listitem> - <listitem><para>Both of the above can result in the message table becoming far larger than - necessary.</para></listitem> -</itemizedlist> - -</para> - -<section id="app01-menus-auto"><title>Autoconnection</title> -<para> - With autoconnection on, *each* time a menu bar is attached to a dialog every - command item in the menu is connected to a method in the dialog it is - attached to. Either a method constructed from the text of the menu item or - all menu items are connected to a single method. -</para> -<para> - Note that if autoconnection is on, the automatic connection of menu items is - *always* done when a menu bar is attached to a dialog, even if the - connection request way of attaching menu items is also in use. -</para> -<para> - Autoconnection can be explicitly turned on by using: - <programlisting> - <![CDATA[ - ::method setAutoConnection - use strict arg on, msg = "" - ]]> - </programlisting> - *before* a menu bar is attached to a dialog. -</para> -<para> - setAutoConnection() can also be used to turn autoconnection off at any time. -</para> -<variablelist><title>Font Filename Extensions</title> - <varlistentry> - <term>BinaryMenuBar</term> - <listitem><para>Turning autoconnection on can also be specified in the new method of a - .BinaryMenuBar</para></listitem> - </varlistentry> - <varlistentry> - <term>UserMenuBar:</term> - <listitem><para>Autoconnection can be turned on in .UserMenuBar~new(). - Autoconnection can also be turned on explicitly using setAutoConnection() - after the UserMenuBar is created, but before it is attached to a dialog. - </para></listitem> - </varlistentry> - <varlistentry> - <term>ScriptMenuBar:</term> - <listitem><para>Similar to a UserMenuBar, autoconnection can be turned on after - the menu is created but before it is attached to a dialog.</para></listitem> - </varlistentry> - <varlistentry> - <term>PopupMenu</term> - <listitem><para>When a popup menu is used as a submenu of a menu bar, autoconnection is - meaningless. A submenu can not be attached or assigned to a dialog.</para> - <para>When a popup menu is used as a context menu, autoconnection can be turned - on, either explicitly using setAutoConnection() or by using the autoConnect - option in the assignTo() method.</para> - <para>Note that setAutoConnection() has to be invoked on the top-level menu of the - context menu. Invoking it on a submenu of the context menu would have no - effect.</para> - <para>When the track() or show() methods are used with a popup menu, - autoconnection is ignored.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>insertItem() method.</term> - <listitem> - <para>If autoconnection is turned on in the menu bar that the item is inserted - into and the menu bar is already attached to a dialog, then the item will be - automatically connected, using either the autoconnectionMethod name or a - method name constructed from the text of the item.</para> - <para>This will *only* be done if the item is being inserted by ID and being - inserted into a menu bar, not being inserted into a popup menu.</para> - </listitem> - </varlistentry> -</variablelist> - -</section> - -<section id="app01-menus-requ"><title>Connection Request</title> -<para> - A connection request is made when a menu command item is to be connected to - a specific method name in a dialog, before the menu bar has been attached to - a dialog. Obviously it is impossible to connect the item to a dialog - method, before it is known what dialog the menu bar is going to be connected - to. -</para> -<para> - Connection requests are made by specifying a method to invoke when adding a - command item to a UserMenuBar through addItem(), or by specifying the - connect argument in .ScriptMenu~new(). -</para> -<para> - The request can also, possibly, be made by specifying a method to inovke - when inserting a command item through insertItem(), see below. -</para> -<variablelist><title>Font Filename Extensions</title> - <varlistentry> - <term>BinaryMenuBar</term> - <listitem><para>A connection request is not used, except possibly though the insertItem() - method, see below.</para></listitem> - </varlistentry> - <varlistentry> - <term>UserMenuBar</term> - <listitem><para>In a UserMenuBar, a connection request can be made in the addItem() method - by specifying a method name as the last argument to addItem()</para></listitem> - </varlistentry> - <varlistentry> - <term>ScriptMenuBar</term> - <listitem><para>Connection requests are made by using the 'connnect' argument in the - ScriptMenuBar~new() method. If 'connect' is true, then a connection request - is made for each command item found in the resource script, using a method - name constructed from the text of the command item.</para></listitem> - </varlistentry> - <varlistentry> - <term>PopupMenu</term> - <listitem><para>Connection requests have no meaning in a popup menu, - there is no such thing.</para></listitem> - </varlistentry> - <varlistentry> - <term>insertItem() method</term> - <listitem><para>A connection request can be made through the insertItem() method under these - specific conditions. The insertItem() is invoked on a menu bar, not using - by position, and the menu bar is not currently attached to a dialog. Then a - connection request is made by using the last arguments to the method, - 'connect' and possiblly 'methodName.' If the menu bar is already attached - to a dialog, then those last two arguments connect the item immediatley. - </para></listitem> - </varlistentry> -</variablelist> - -</section> - -</section> - -<section id="app01-bams"><title>Menus and Pushbuttons Method Connection</title> -<para> - This note deals with connection of Command Events from menu items and pushbuttons - to ooRexx methods. -</para> - -<section id="app01-bams-btns"><title>Buttons</title> <!-- 1 --> - -<section id="app01-bams-btns-auto"><title>Auto-connection</title><!-- 1.1 --> -<para> -For a UserDialog, the createPushButton() method takes an argument that specifies -the method to connect for the click event. For an RcDialog, the new method allows -you to automatically connect the buttons: - <programlisting> - <![CDATA[ - >>--init(--script--,--id--+------------+--+---------+--+--------+--+------------+--)-->< - +-,-dlgData.-+ +-,-hFile-+ +-,-opts-+ +-,-expected-+ - ]]> - </programlisting> -Section 6.2.1 of the doc is correct for the opts argument; use the CONNECTBUTTONS, -CONNECTRADIOS, or CONNECTCHECKS keyword(s). -</para> -</section> -<section id="app01-bams-btns-expl"><title>Explicit Connection</title><!-- 1.2 --> -<para> - Use the method connectButtonEvent() -</para> -</section> -</section> -<section id="app01-bam-menus"><title>Menu Items</title><!-- 2 --> -<para> - When a user clicks on a menu item (that is not a separator or a sub-menu), then a menu command event is raised. [See - section 25.2 of the ooDialog Reference] - With menu objects there are 2 basic ways to connect the menu command events to - a method in the Rexx dialog. Either the command events can be connected automatically - by the ooDialog framework. Or the command events can be connected explicitly by the - programmer. -</para> -<section id="app01-bam-menus-auto"><title>Auto-connection</title><!-- 2.1 --> -<para>For the BinaryMenuBar, ScriptMenuBar, and UserMenuBar, the new() method has an optional - argument towards the end of the argument list for automatically connecting the - menu items. When set to .true, all the menu command items are automatically connected - when the menu bar is attached to a dialog. The programmer provides methods whose names - are the same as the captions (or visible text) of the menu items (excluding blanks - and any trailing dots). Thus for a menu item that has the caption Do this the programmer would provide a method with - the name dothis. -</para> -</section> -<section id="app01-bam-explicit"><title>Explicit connection</title><!-- 2.2 --> -<para> - Use the connectCommandEvent method of the Menu class (you can invoke it on the - MenuBar class if you wish). See section 25.3.48 of the ooDialog Reference. -</para> -</section> -</section> - -<section id="app01-bam-notes"><title>Notes</title><!-- 3 Notes --> -<para> - 1. Do not use both auto and explicit for same menu command item. - 2. The connectMenuEvent method is actually for connecting menu events, not menu -command events. E.g there is a menu event notification when the OS is about to -display a menu. A menu command event is sent when a user clicks on a menu item. -</para> -</section> -</section> - -</appendix> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-06-05 23:08:22
|
Revision: 7846 http://oorexx.svn.sourceforge.net/oorexx/?rev=7846&view=rev Author: osims Date: 2012-06-05 23:08:15 +0000 (Tue, 05 Jun 2012) Log Message: ----------- Delete 'appendix01' from makefile. Correct four bad tags in Chapter04. Modified Paths: -------------- docs/trunk/oodguide/Chapter04.xml docs/trunk/oodguide/Makefile Modified: docs/trunk/oodguide/Chapter04.xml =================================================================== --- docs/trunk/oodguide/Chapter04.xml 2012-06-05 03:44:42 UTC (rev 7845) +++ docs/trunk/oodguide/Chapter04.xml 2012-06-05 23:08:15 UTC (rev 7846) @@ -37,7 +37,7 @@ # ######################################################################### --> -<!-- Chapter04 - Using Resource Dialogs v01-00 02Jun12 +<!-- Chapter04 - Using Resource Dialogs v01-00 05Jun12 4.1 Naming and Coding Conventions 4.1.1 Naming Conventions 4.1.2 Coding Conventions @@ -50,7 +50,7 @@ 4.3.3.2 The update and recordChanges Methods Changes: - v01-00 02Jun12: First version. + v01-00 05Jun12: First version. --> <chapter id="chapFour"> <title>Using Resource Dialogs</title> @@ -483,7 +483,7 @@ self~connectButtonEvent("IDC_CUST_BTN_RECORDCHANGES","CLICKED",recordChanges) ]]> </programlisting>This is an example of specifying an "event handler" (inbound active behavior). - <indexerm><primary>Event handler</primary></indexerm> + <indexterm><primary>Event handler</primary></indexterm> Suppose the user presses the "Record Changes" button. The Windows runtime signals the event, which ooDialog picks up. The above statement declares that this event - i.e.that the pushbutton identified in the <computeroutput>.h</computeroutput> file as @@ -501,7 +501,7 @@ the ooDialog Reference. Note also that event-handling methods must be PUBLIC, since they are invoked from outside the ooRexx dialog class by the underlying ooDialog code (and of course an ooRexx method is public unless PRIVATE is specified). - <indexerm><primary>Event handler</primary><secondary>Public method</secondary></indexerm> + <indexterm><primary>Event handler</primary><secondary>Public method</secondary></indexterm> <indexterm><primary>Unguarded method</primary></indexterm></para> <para>Specification of active controls is generally done in the <emphasis role="italic" >initDialog</emphasis> method. Indeed, in the @@ -674,7 +674,6 @@ custControls[ecCustName]~setReadOnly(.false) ]]> </programlisting> - <indexterm></indexterm> </para> <para>Pushbuttons are enabled by invoking <emphasis role="italic">enableControl</emphasis> on the dialog with the control's symbolic ID as the single parameter, as shown Modified: docs/trunk/oodguide/Makefile =================================================================== --- docs/trunk/oodguide/Makefile 2012-06-05 03:44:42 UTC (rev 7845) +++ docs/trunk/oodguide/Makefile 2012-06-05 23:08:15 UTC (rev 7846) @@ -45,7 +45,6 @@ xml_FILES = oodguide.xml \ - appendix01.xml \ appendix02.xml \ appendix03.xml \ appendix04.xml \ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <os...@us...> - 2012-06-07 22:02:28
|
Revision: 7858 http://oorexx.svn.sourceforge.net/oorexx/?rev=7858&view=rev Author: osims Date: 2012-06-07 22:02:21 +0000 (Thu, 07 Jun 2012) Log Message: ----------- ooDialog Guide - Final polish (including minor corrections) to the Appendices. Modified Paths: -------------- docs/trunk/oodguide/appendix02.xml docs/trunk/oodguide/appendix03.xml docs/trunk/oodguide/appendix04.xml Property Changed: ---------------- docs/trunk/oodguide/appendix04.xml Modified: docs/trunk/oodguide/appendix02.xml =================================================================== --- docs/trunk/oodguide/appendix02.xml 2012-06-07 15:48:09 UTC (rev 7857) +++ docs/trunk/oodguide/appendix02.xml 2012-06-07 22:02:21 UTC (rev 7858) @@ -38,20 +38,13 @@ ######################################################################### --> -<!-- Appendix 02 - Dialog Data and AutoDetection v00-03 15Aug11 +<!-- Appendix 02 - Dialog Data and AutoDetection v01-00 07Jun12 This is an illustration, through sample code, of the use of Dialog Data, including AutoDetection. Changes: - v00-01: First version (??0711) - v00-02 11Aug11: Added bit about -1 for static text. - v00-03 15Aug11: Changed title (added "AutoDetection"). + v01-00 07Jun12: First version. - ********* INCLUDE Res ID of -1 for Static Text - not auto-detected. - Mark's email of 11Aug11 ********* - - 13Aug11 - Decided not do do this - so no change to committed file - - i.e. committed file is and should be at v00-01. --> <appendix id="apx-dlgdata"> <title id="dlgdata.title">Dialog Attributes and AutoDetection</title> @@ -73,8 +66,7 @@ <para>This function is still supported by ooDialog. The compound symbol is often referred to as "dialog data", and the process of automatically moving data between the ooRexx dialog and the underlying Windows constructs is called "automatic data detection" or - "auto detection" for short. A full - description of this capability is provided in section 3.6 of the ooDialog Reference. The aim of this appendix + "auto detection" for short. The aim of this appendix is to illustrate, through a simple example, how automatic data detection is coded. The example, <computeroutput>ASimpleDialog.rex</computeroutput>, can be found in the <computeroutput>Samples\DlgData</computeroutput> folder. When executed, the dialog looks like this: @@ -144,16 +136,17 @@ parameter - <emphasis role="italic">dlgData.</emphasis> - is the stem variable that contains the data - that is the attribute values - to be placed in the dialog's controls. Finally, the fourth parameter is the header file, which can be omitted if the statement - <computeroutput>.application~useGlobalConstDir("O","ASimpleDialog.h")</computeroutput> is + <computeroutput>.application~useGlobalConstDir("O", "ASimpleDialog.h")</computeroutput> is placed at the start of the program. </para> <para>The class <computeroutput>ASimpleDialog</computeroutput> is defined at the end of the program. Note the extreme simplicity of coding a - simple form-filling dialog class. No methods are needed; the superclass, + simple form-filling dialog class. No methods are needed - the dialog consists + of a single <computeroutput>::CLASS</computeroutput> statement. The superclass, <computeroutput>RcDialog</computeroutput>, provides all the function needed. </para> <para>Section (3) of the code shows how data is retrieved from the controls via <emphasis - role="italic">dlgData.</emphasis> after the dialog has been closed by the user. Note that a - mixture numeric and symbolic IDs can be used, as illustrated by statements such as <emphasis + role="italic">dlgData</emphasis> after the dialog has been closed by the user. Note that a + mixture of numeric and symbolic IDs can be used, as illustrated by statements such as <emphasis role="italic">disagree = dlgData.1004</emphasis>. Indeed, a control can be referenced by its symbolic ID in one place and by its numeric ID in another, as illustrated by the use of both <computeroutput>IDC_EDIT1</computeroutput> and <computeroutput>1002</computeroutput> to @@ -166,27 +159,24 @@ program <computeroutput>ASimpleDialog2.rex</computeroutput> is included in the <computeroutput>samples\DlgData</computeroutput> folder together with its *.dll file. </para> -<para>Finally, when desired, auto detection can be turned off. <indexterm> - <primary>AutoDetection</primary> - </indexterm> - <indexterm> - <primary>Automatic data detection</primary> - <secondary>turning off</secondary> - </indexterm> The Dialog Object (see ooDialog Reference chapter 3) sends itself an <emphasis - role="italic">initAutoDetection</emphasis> message when a dialog is instantiated. By - default, auto detection is turned on. If desired, a subclass can turn it off by intercepting - the message and issuing a <emphasis role="italic">noAutoDetection</emphasis> message to - <emphasis role="italic">self</emphasis>. Try adding the following method to <emphasis - role="bold">ASimpleDialog</emphasis> - <programlisting> +<para>Finally, when desired, there are two ways to turn auto detection off (by default it is turned on). + <indexterm><primary>AutoDetection</primary><secondary>turning off</secondary></indexterm> + First, by the Application Manager (see the ooDialog Reference), and second programmatically + by intercepting the <emphasis role="italic">initAutoDetection</emphasis> message. + This is automatically sent to the dialog by the ooDialoog framework when the dialog + is instantiated. To turn auto detection off, just invoke <emphasis role="italic">noAutoDetection</emphasis> + on <emphasis role="italic">self</emphasis>. Try adding the following method to + <emphasis role="bold">ASimpleDialog</emphasis> + <programlisting> <![CDATA[ ::CLASS ASimpleDialog SUBCLASS RcDialog ::method initAutoDetection self~noAutoDetection ]]> - </programlisting>When the program is run, the edit control is blank. On pressing "OK", the + </programlisting> + When the program is run, the edit control is blank. On pressing "OK", the dialog closes and an error is reported on the console. The error occurs because the radio button "data" (i.e. a boolean) is not returned, and so an "if" statement fails because it's expecting a boolean value to be tested. </para> -</appendix> \ No newline at end of file +</appendix> Modified: docs/trunk/oodguide/appendix03.xml =================================================================== --- docs/trunk/oodguide/appendix03.xml 2012-06-07 15:48:09 UTC (rev 7857) +++ docs/trunk/oodguide/appendix03.xml 2012-06-07 22:02:21 UTC (rev 7858) @@ -38,16 +38,14 @@ ######################################################################### --> -<!-- Appendix 03 - Testing Popups v00-05 16Mar12 +<!-- Appendix 03 - Testing Popups v01-00 07Jun12 An illustration of (a) how popups can be tested in stand-alone mode with a single code base, and (b) how "child" dialogs can be visually offset from the "parent" dialog that pops up the "child". Both supported by examples in Exercises\Samples\Popups folder. Changes: - v00-01 17Sep11: First version - v00-04 04Mar12: Added offset capability. - v00-05 16Mar12: Revised to take account of new simpified offset function. + v01-00 07Jun12: First version. --> <appendix id="apx-satesting"> @@ -57,8 +55,8 @@ <indexterm><primary>Standalone testing</primary></indexterm> <para>This appendix discusses two separate aspects of "popup" dialogs. The first aspect is testing popped-up dialogs in stand-alone mode - that is, without having to run the "parent" dialog - from which the popped-up dialog is launched. Second, the issue of how a popped-up dialog can - be visually offset from its "parent" so that it does not obscure the parent is addressed. </para> + from which the popped-up dialog is launched. The second aspect is the issue of how a popped-up dialog can + be visually offset from its "parent" so that it does not obscure the parent. </para> <section id="apx-satesting-sa"><title>Stand-Alone Testing</title> <para>Consider four dialogs called Parent, Child, Grandchild, and GreatGrandChild. @@ -70,8 +68,8 @@ </para> <para>When testing an application, there is often a need to test an individual dialog which, in the application, is a "child" that's invoked by a "parent" dialog which issues <emphasis - role="italic">self~popUpAsChild(...)</emphasis> rather than - <emphasis role="italic">self~execute(...)</emphasis> to surface the child dialog. + role="italic">self~popUpAsChild(...)</emphasis> - rather than + <emphasis role="italic">self~execute(...)</emphasis> - to surface the child dialog. In addition, popping-up requires the parent dialog to be specified as a method argument: <emphasis role="italic">self~popUpAsChild(parent,...)</emphasis>. </para> @@ -108,8 +106,8 @@ may invoke one or more GreatGrandChild dialogs. The child and grandchild dialogs are "intermediate" dialogs. The GreatGrandChild dialog is a "leaf" dialog - that is, it does not invoke any other dialog (except of course those integral to its own functioning such as an - About box or a data entry sub-dialog). For completeness, the Parent dialog is included in - the following. <programlisting> + About box or a data entry sub-dialog). + <programlisting> <![CDATA[ The Parent Dialog: @@ -188,8 +186,8 @@ <computeroutput>Popups.rex</computeroutput>. Try running the program with an offset of 100 by entering <computeroutput>OffsetPopups 100</computeroutput> on a command prompt. You'll see that popped-up dialogs are offset from the dialogs from which they're popped up, and do - not now obscure them. <computeroutput>OffsetPopups ?</computeroutput> provides help on the - available arguments. </para> + not now obscure them. Entering <computeroutput>OffsetPopups ?</computeroutput> provides help. + </para> <para>In <computeroutput>OffsetPopups.rex</computeroutput>, all classes are subclassed from a <computeroutput>View</computeroutput> class (itself subclassed from <computeroutput>UserDialog</computeroutput>) which has one class attribute and two methods, @@ -231,16 +229,12 @@ and not partly off the screen. </para> <para>In detail: - - (the variable <emphasis role="italic">popupPos</emphasis>) - (as the variable <emphasis role="italic">dlgPos</emphasis>) - <itemizedlist> <listitem><para><emphasis role="bold"><emphasis role="italic">getPopupPos</emphasis></emphasis> - This method is used by the senior dialog to establish where on the screen the junior dialog is to appear (relative to the senior dialog). The first statement <emphasis role="italic">popupPos = self~getRealPos</emphasis> gets the - position of the senior dialog as a point object (ooDialog Reference 10.11) whose + position of the senior dialog as a point object (see ooDialog Reference) whose attributes are the point's <emphasis role="italic">x</emphasis> and <emphasis role="italic">y</emphasis> screen coordinates (that is, the top-left corner of the dialog). The point object is assigned to <emphasis role="italic">popupPos</emphasis>. @@ -248,7 +242,7 @@ </listitem> <listitem><para> The second statement, <emphasis role="italic">offset = .View~offsetAmount</emphasis> - gets the offest amount from a class attribute.</para> + gets the offset amount stored in the class attribute.</para> </listitem> <listitem><para>Then the statement <emphasis role="italic">popupPos~incr(offset,offset)</emphasis> increments @@ -257,8 +251,8 @@ That is, <emphasis role="italic">popupPos</emphasis> is now the desired new position of the junior dialog.</para> </listitem> - <listitem><para>Finally, the desired junior dialog's position is returned to - the senior dialog, which will then pass it to the junior dialog when the + <listitem><para>Finally, the desired junior dialog's position is returned, and + the senior dialog then passes it to the junior dialog when the latter is created via its <emphasis role="italic">newInstance</emphasis> method.</para> </listitem> </itemizedlist> @@ -274,7 +268,7 @@ friendly.So...</para> </listitem> <listitem><para>... the last statement (<emphasis role="italic">self~ensureVisible()</emphasis>) - ensuresthat the current dialog is wholly visible. However, + ensures that the current dialog is wholly visible. However, because it's so fast, you don't see this re-positioning. To see the re-positioning, insert <emphasis role="italic">call sysSleep(2)</emphasis> just before the last statement, run the program, and move the parent dialog to the bottom of the screen. Modified: docs/trunk/oodguide/appendix04.xml =================================================================== --- docs/trunk/oodguide/appendix04.xml 2012-06-07 15:48:09 UTC (rev 7857) +++ docs/trunk/oodguide/appendix04.xml 2012-06-07 22:02:21 UTC (rev 7858) @@ -1,213 +1,212 @@ -<!--######################################################################### - # - # 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-04 23Apr12 - Shows the methods invoked during dialog creation. - - Changes: - v00-01 08Jan12: First version - v00-02 19Jan12: minor additions/corrections. - v00-03 23Feb12: Decrease table width so it's not off the edge of the page(!). - v00-04 23Apr12: Table still off edge of page - try again. ---> - -<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> or - <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="75.00pt"> <!-- was 78.75pt --> - <colspec colnum="2" colname="c2" colwidth="100.0pt"> <!-- was 106.5pt --> - <colspec colnum="3" colname="c3" colwidth="100.0pt"> <!-- was 106.5pt --> - <colspec colnum="4" colname="c4" colwidth="100.0pt"> <!-- was 106.5pt --> - <colspec colnum="5" colname="c5" colwidth="95.00pt"> <!-- was 96.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>Class Method</entry> - </row> - <row> - <entry><emphasis role="italic"> init</emphasis></entry> - <entry> Yes.</entry> - <entry> - <literallayout> Yes. - Create Menubar - <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 - - 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 Under- - lying 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">ctl=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">ctl=self~new...(...)</emphasis> - - Attach Menubar using - <emphasis role="italic">~attachTo(self)</emphasis></literallayout></entry> - <entry><literallayout> Create "proxies" for - controls and initialize - them using - <emphasis role="italic">ctl=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 class, 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. This 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. For a - <computeroutput>UserDialog</computeroutput> the dialog template must be created using - self~create(...) instructions. For an <computeroutput>RcDialog</computeroutput> the dialog - template is normally fully-defined by the *.rc file, but can optionally be enhanced here. - However, in the case of <computeroutput>ResDialog</computeroutput>, the dialog template is - fully-defined by the *.dll file, and cannot be changed programmatically. Therefore, a - <emphasis role="italic">defineDialog</emphasis> message is not sent to a - <computeroutput>ResDialog</computeroutput>.</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>The last method in the table - <emphasis role="italic">initDialog</emphasis> (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 pre-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. It's - worth remembering that the "init" in <emphasis role="italic">initDialog</emphasis> means - "initialize" - not to be confused with the ooRexx <emphasis role="italic">init</emphasis> - method. </para> - <para>Finally, although the creation of a menubar is mentioned in the table, technically it is - not part of dialog creation. A menubar can be created any time. However, it can only be - attached to a dialog after the underlying dialog is created. Thus the first opportunity to - attach a menubar to the dialog is in the <emphasis role="italic">initDialog</emphasis> method; - but it can be done later. </para> - -</appendix> - +<!--######################################################################### + # + # 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 v01-00 07Jun12 + Shows the methods invoked during dialog creation. + + Changes: + v01-00 07Jun12: 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> or + <computeroutput>ResDialog</computeroutput>. Menu creation is included even though this is + technically quite separate from dialog creation, and does not have to be done + in the <emphasis role="italic">init</emphasis> method.</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="75.00pt"> <!-- was 78.75pt --> + <colspec colnum="2" colname="c2" colwidth="100.0pt"> <!-- was 106.5pt --> + <colspec colnum="3" colname="c3" colwidth="100.0pt"> <!-- was 106.5pt --> + <colspec colnum="4" colname="c4" colwidth="100.0pt"> <!-- was 106.5pt --> + <colspec colnum="5" colname="c5" colwidth="95.00pt"> <!-- was 96.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>Class Method</entry> + </row> + <row> + <entry><emphasis role="italic"> init</emphasis></entry> + <entry> Yes.</entry> + <entry> + <literallayout> Yes. + Create Menubar + <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 - + 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 Under- + lying 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">ctl=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">ctl=self~new...(...)</emphasis> + + Attach Menubar using + <emphasis role="italic">~attachTo(self)</emphasis></literallayout></entry> + <entry><literallayout> Create "proxies" for + controls and initialize + them using + <emphasis role="italic">ctl=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 class, 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 the ooDialog + Reference) is invoked automatically by the superclass' <emphasis role="italic">init</emphasis> + method. This method provides for the creation of the "Dialog Template" + (see the ooDialog Reference) - that is, the layout of controls on the dialog. For a + <computeroutput>UserDialog</computeroutput> the dialog template must be created using + self~create(...) instructions. For an <computeroutput>RcDialog</computeroutput> the dialog + template is normally fully-defined by the *.rc file, but can optionally be enhanced here. + However, in the case of <computeroutput>ResDialog</computeroutput>, the dialog template is + fully-defined by the *.dll file, and cannot be changed programmatically. Therefore, a + <emphasis role="italic">defineDialog</emphasis> message is not sent to a + <computeroutput>ResDialog</computeroutput>.</para> + <para>On exit from the <emphasis role="italic">defineDialog</emphasis> method, the dialog + template is established. </para> + <para>The "underlying dialog" (see the ooDialog Reference) is then created and + surfaced (made visible to the user) by invoking the superclass' + <emphasis role="italic">execute</emphasis> method.</para> + <para>The last method in the table - <emphasis role="italic">initDialog</emphasis> - is + provided for the programmer to initialize the various controls, + e.g. setting an edit control to its initial data value, or pre-selecting 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. It's + worth remembering that the "init" in <emphasis role="italic">initDialog</emphasis> means + "initialize" - not to be confused with the ooRexx <emphasis role="italic">init</emphasis> + method. </para> + <para>Finally, although the creation of a menubar is mentioned in the table, technically it is + not part of dialog creation. A menubar can be created any time. However, it can only be + attached to a dialog after the underlying dialog is created. Thus the first opportunity to + attach a menubar to the dialog is in the <emphasis role="italic">initDialog</emphasis> method; + but it can be done later. </para> + +</appendix> + Property changes on: docs/trunk/oodguide/appendix04.xml ___________________________________________________________________ Added: svn:eol-style + native This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |