Menu
▾
▴
[Oorexx-svn] SF.net SVN: oorexx-code-0:[9089] ooDialog/branches/4.2.2/doc/oodguide/en-US /Chapter02.xml
|
From: <os...@us...> - 2013-03-12 16:44:17
|
Revision: 9089
http://sourceforge.net/p/oorexx/code-0/9089
Author: osims
Date: 2013-03-12 16:44:14 +0000 (Tue, 12 Mar 2013)
Log Message:
-----------
Correct emphases to conform with revised conventions. Also minor tidy-up of spacing plus a very minor text change.
Modified Paths:
--------------
ooDialog/branches/4.2.2/doc/oodguide/en-US/Chapter02.xml
Modified: ooDialog/branches/4.2.2/doc/oodguide/en-US/Chapter02.xml
===================================================================
--- ooDialog/branches/4.2.2/doc/oodguide/en-US/Chapter02.xml 2013-03-12 03:41:15 UTC (rev 9088)
+++ ooDialog/branches/4.2.2/doc/oodguide/en-US/Chapter02.xml 2013-03-12 16:44:14 UTC (rev 9089)
@@ -43,18 +43,19 @@
#########################################################################
-->
-<!-- Chapter02 - In The Beginning v01-02 02Jan13
+<!-- Chapter02 - In The Beginning v01-03 12Jan13
Changes:
v01-00 31May12: First version.
v01-01 29Jly12: Delete reference to (spurious) "Exercise01".
v01-02 02Jan13: Change chapter title from "In The Beginning" to "Hello ooDialog World".
+ v01-03 12Jan13: Minor clean-up after another proof-read.
-->
<chapter id="chapTwo"><title>Hello ooDialog World</title>
<indexterm><primary>overview</primary></indexterm>
<para>
- The whole purpose of ooDialog is to enable ooRexx developers to provide users with
+ The 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 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
@@ -111,17 +112,17 @@
<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 folder
- <computeroutput>C:\Program Files\ooRexx\samples\oodialog\userGuide\exercises\Exercise02</computeroutput>
+ Try running it - it's the file <emphasis role="bold">HelloWorld.rex</emphasis> in the folder
+ <emphasis role="bold">C:\Program Files\ooRexx\samples\oodialog\userGuide\exercises\Exercise02</emphasis>
(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>
+ The Command Prompt window that appears with the <emphasis role="bold">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):
+ For now, let's look at the <emphasis role="bold">Hello World</emphasis> code (excluding comments):
</para>
<figure id="fig01"><title>The 'Hello World' Dialog</title>
<mediaobject>
@@ -132,18 +133,16 @@
</figure>
<para>
First, there's code that kicks things off:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
dlg = .HelloWorld~new
dlg~execute("SHOWTOP", IDI_DLG_OOREXX)
- ]]>
- </programlisting>
+]]></programlisting>
The first statement creates an instance of the class <computeroutput>HelloWorld</computeroutput>,
- and assigns the instance to the variable <emphasis role="italic">dlg</emphasis>
+ and assigns the instance to the variable <computeroutput>dlg</computeroutput>
(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
+ The second statement invokes the <computeroutput>execute</computeroutput> 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
+ The first parameter <computeroutput>SHOWTOP</computeroutput> is one of several ways of defining
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
@@ -152,40 +151,34 @@
<para>
Note that the usual naming conventions are observed: upper camel case for classes
(e.g. <computeroutput>HelloWorld</computeroutput>) and lower camel case for
- variables (including of course instance variables - e.g. <emphasis role="italic">dlg</emphasis>).
+ variables (including of course instance variables - e.g. <computeroutput>dlg</computeroutput>).
</para>
<para>
Second, there's a directive to ooRexx to use ooDialog:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
::REQUIRES "ooDialog.cls"
- ]]>
- </programlisting>
+]]></programlisting>
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[
+<programlisting><![CDATA[
16 *-* ::class 'HelloWorld' subclass UserDialog
Error 98 running ... Exercise02\HelloWorld.rex line 58: Execution error
Error 98.909: Class "USERDIALOG" not found
- ]]>
- </programlisting>
+]]></programlisting>
Note that it's <computeroutput>UserDialog</computeroutput> (the superclass
for <computeroutput>HelloWorld</computeroutput>) that's not found.
- This is because the <emphasis role="italic">::requires ooDialog.cls</emphasis> statement
+ This is because the <computeroutput>::requires ooDialog.cls</computeroutput> statement
not only says we're using ooDialog, but also provides
access to all the classes provided <emphasis role="italic">by</emphasis> ooDialog.
</para>
<para>
Finally, there's the definition of the class <computeroutput>HelloWorld</computeroutput>:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
::CLASS HelloWorld SUBCLASS UserDialog
::METHOD init
forward class (super) continue
self~create(30, 30, 257, 123, "Hello World", "CENTER")
- ]]>
- </programlisting>
+]]></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).
@@ -194,18 +187,18 @@
meet a simpler way of defining the dialog layout.
</para>
<para>
- The second line defines the <emphasis role="italic">init</emphasis> method of
+ The second line defines the <computeroutput>init</computeroutput> method of
<computeroutput>HelloWorld</computeroutput>, and the third line forwards the
- <emphasis role="italic">init</emphasis> message to the superclass which then
+ <computeroutput>init</computeroutput> message to the superclass which then
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
+ But why use <computeroutput>forward</computeroutput> instead of
+ <computeroutput>self~init:super</computeroutput>? The reason is that
+ <computeroutput>forward</computeroutput> applies not only to the method but
also to all its arguments, whatever these may be. Which is exactly what's required here.
</para>
<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>.
+ Finally, the last line sends a <computeroutput>create</computeroutput> message to
+ <computeroutput>self</computeroutput> and hence to <computeroutput>UserDialog</computeroutput>.
This method defines the "template" to be used for the dialog. The parameters are as follows:
<itemizedlist>
<listitem><para>
@@ -235,13 +228,11 @@
</para>
<para>With this instance of the <computeroutput>HelloWorld</computeroutput> class having
been set up properly, the dialog is actually surfaced (made visible) by the
- <emphasis role="italic">execute</emphasis> message (handled by HelloWorld's superclass)
+ <computeroutput>execute</computeroutput> message (handled by HelloWorld's superclass)
sent by the second statement in the program which was:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
dlg~execute("SHOWTOP", IDI_DLG_OOREXX)
- ]]>
- </programlisting>
+]]></programlisting>
</para>
<para>
Now let's add some behavior to the dialog. We're going to build a "Words of Wisdom"
@@ -269,8 +260,7 @@
Now let's look at the code.
The first seven lines (excluding comments and blank lines)
are essentially the same as the first seven in <computeroutput>HelloWorld.rex</computeroutput>:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
dlg = .WordsOfWisdom~new
dlg~execute("SHOWTOP", IDI_DLG_OOREXX)
::REQUIRES "ooDialog.cls"
@@ -278,18 +268,15 @@
::METHOD init
forward class (super) continue
self~create(30, 30, 257, 123, "Words of Wisdom", "CENTER")
- ]]>
- </programlisting>
+]]></programlisting>
However, a <emphasis role="italic">defineDialog</emphasis> method has been added:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
::METHOD defineDialog
self~createPushButton(901, 142, 99, 50, 14, "DEFAULT", "More wisdom")
self~createPushButton(IDCANCEL, 197, 99, 50, 14, ,"Cancel")
self~createStaticText(-1, 40, 40, 200, 20, , -
"Complex problems have simple solutions"||.endofline||"- which are wrong.")
- ]]>
- </programlisting>
+]]></programlisting>
This method is invoked automatically by the superclass, and consists of three
statements each of which creates a control. The first two each create a pushbutton:
<itemizedlist>
@@ -311,7 +298,7 @@
is the text shown on the button.
</para></listitem>
<listitem><para>
- A "Cancel" pushbutton, whose ID <emphasis role="italic">IDCANCEL</emphasis>
+ A "Cancel" pushbutton, whose ID <computeroutput>IDCANCEL</computeroutput>
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
@@ -329,7 +316,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="bold">More wisdom</emphasis> button work,
which we now do in <computeroutput>Wow2.rex</computeroutput>.
</para>
@@ -338,10 +325,10 @@
<section id="visBehavior2"><title>Making The Controls Work</title>
<para>
First, run <computeroutput>Wow2.rex</computeroutput>. When you click the
- <emphasis role="italic">More wisdom</emphasis> pushbutton,
+ <emphasis role="bold">More wisdom</emphasis> pushbutton,
you see different text appearing in the center of the screen, replacing the previous text.
By the way, you'll also see debug information appear on the command prompt each time you
- click the <emphasis role="italic">More wisdom</emphasis> button - there's
+ click the <emphasis role="bold">More wisdom</emphasis> button - there's
a "say" statement in the code that's not mentioned here, but you can easily find it.
The real question at the moment is: how do we create the pushbutton's visible behavior?
</para>
@@ -356,8 +343,8 @@
</para>
<para>
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
+ to a method. However, a user action is actually signaled by an event emitted from the underlying
+ Windows GUI software infrastructure. ooDialog connects that event to
a method in the ooRexx dialog object. So the source of the event (the user action) is not ooDialog.
This means that if you want to capture a user action that the Windows infrastructure doesn't
capture (for example hovering the mouse over an edit control), then there's no way ooDialog
@@ -365,37 +352,34 @@
</para>
<para>
Having said that, one of the simplest ways of having a user action connected to an ooRexx
- method is by supplying the name of the method as a parameter of the actionable widget.
+ method is by supplying the name of the method as a parameter of the actionable control.
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>defineDialog</computeroutput> method - are almost identical to those of
<computeroutput>wow.rex</computeroutput>, with two significant changes.
The method is as follows:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
::method defineDialog
self~createPushButton(901, 142, 99, 50, 14, "DEFAULT", "More wisdom", OkClicked)
self~createPushButton(IDCANCEL, 197, 99, 50, 14, ,"Cancel")
self~createStaticText(101, 40, 40, 200, 40, , "Click 'More wisdom'")
- ]]>
- </programlisting>
+]]></programlisting>
</para>
<para>
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>.
+ <computeroutput>self~createPushButton</computeroutput>
+ has an additional parameter <computeroutput>okClicked</computeroutput>.
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,
- the statement <emphasis role="italic">self~createStaticText</emphasis> has the
+ clicks on the <emphasis role="bold">More wisdom</emphasis> pushbutton. Secondly,
+ the statement <computeroutput>self~createStaticText</computeroutput> 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>
- However, the major change to the program is the new <emphasis role="italic">okClicked</emphasis> method that
+ However, the major change to the program is the new <computeroutput>okClicked</computeroutput> method that
picks a "words of wisdom" text and displays it. Pseudocode for this method is as follows:
- <programlisting>
- <![CDATA[
+<programlisting><![CDATA[
Method okClicked
Create array 'arrWow' and add a 'words of wisdom' text strings to each of seven
array elements.
@@ -403,8 +387,7 @@
Pick a "words of wisdom" text randomly from 'arrWow'
Show that text in the static text field.
return
- ]]>
- </programlisting>
+]]></programlisting>
Have a look at it the code that implements this method in <computeroutput>Wow2.rex</computeroutput>.
Note that the penultimate pseudocode statement above - "show that text in
the static text field" - is implemented in two steps. First the statement
@@ -424,9 +407,6 @@
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>
-
</section>
-
-</chapter>
\ No newline at end of file
+</chapter>
|