Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[r8763]: docs / trunk / oodguide / en-US / appendix02.xml Maximize Restore History

Download this file

appendix02.xml    188 lines (174 with data), 10.9 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "oodguide.ent">
%BOOK_ENTITIES;
]>
<!--#########################################################################
#
# Description: Open Object Rexx: ooDialog User Guide XML file
#
# Copyright (c) 2012-2013 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 02 - Dialog Data and AutoDetection v01-01 18Dec12
This is an illustration, through sample code, of the use of Dialog Data,
including AutoDetection.
Changes:
v01-00 07Jun12: First version.
v01-01 18Dec12: correct trivial typo.
-->
<appendix id="apx-dlgdata">
<title id="dlgdata.title">Dialog Attributes and AutoDetection</title>
<indexterm><primary>Dialog Attributes</primary></indexterm>
<indexterm><primary>Attributes, of a dialog</primary></indexterm>
<indexterm><primary>dlgdata</primary></indexterm>
<indexterm><primary>Dialog Data</primary></indexterm>
<indexterm><primary>Automatic data detection</primary></indexterm>
<para>Since the early days of ooDialog, a dialog's controls (listboxes, edit controls, radio
buttons, etc.) have been treated as attributes of the dialog object. An ooRexx program could
set the attributes' data values in an ooRexx compound symbol (aka stem variable or compound
variable) before the dialog was created. Then, when the dialog was created, those values were
automatically passed to the controls in the underlying Windows dialog and so were visible to
the user. Data could then be entered or modified by the user. When the user closed the dialog,
the data (whether changed or unchanged) was automatically communicated from the underlying
Windows dialog to the ooRexx dialog and placed in the compound symbol, after which the dialog
closed and returned control to the next ooRexx statement in the program. The data was then
available to the ooRexx programmer in the same compound symbol. </para>
<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. 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:
<figure id="figA0201"><title>A Simple Dialog</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/appendix02-image1.jpg" scale="100" />
</imageobject>
</mediaobject>
</figure>
</para>
<para>The program does the following:
<itemizedlist>
<listitem><para>Sets the value "It's a fine day today." in a dialog attribute value in an edit control.</para></listitem>
<listitem><para>Creates and then displays the dialog.</para></listitem>
<listitem><para>When the dialog is closed, retrieves the attribute value as modified (or not) by the
user.</para></listitem>
<listitem><para>Sets up an appropriate message (this is straight ooRexx and forms the bulk of the
program!).</para></listitem>
<listitem><para>Displays the message in a message box.</para></listitem>
</itemizedlist>
</para>
<para>The ooDialog content of the program is very simple, and is as follows: <programlisting>
<![CDATA[
-- (1) Set text in the edit control:
statement = "It's a fine day today."
dlgData.IDC_EDIT1 = statement
-- (2a) Create the dialog defined by the .rc file:
dlg = .ASimpleDialog~new("ASimpleDialog.rc", IDD_DIALOG1, dlgData., "ASimpleDialog.h" )
-- (2b) Display the dialog:
ret = dlg~execute("SHOWTOP", IDI_DLG_OOREXX)
-- (3) When the dialog is closed, and if the user pressed OK, then retrieve
-- the data provided by the user:
if ret == 1 then do -- if the user pressed OK
statement2 = dlgData.1002 -- get data from the edit control
agree = dlgData.IDC_RADIO1 -- get the state of the radio buttons:
disagree = dlgData.1004
-- (4) Set up the appropriate message to display:
/* a number of lines of ooRexx code */
-- (5) Display a message to respond to the user's choices:
ret = MessageDialog(msg, 0, title, 'OK', icon, 'TOPMOST')
::requires "ooDialog.cls"
::CLASS ASimpleDialog SUBCLASS RcDialog
]]>
</programlisting>As illustrated by section (1) of the code, data is first set up in the stem
<emphasis role="italic">dlgData.</emphasis> by the statement:
<computeroutput>dlgData.IDC_EDIT1 = statement</computeroutput>. Note that the name <emphasis
role="italic">dlgData.</emphasis> is not reserved - it could be any name. When the dialog is
created, the text "It's a fine day today." is automatically placed in the edit control
identified by the symbolic ID <computeroutput>IDC_EDIT1</computeroutput>. </para>
<para>Section (2) creates and displays the dialog. Only two statements are required to do this: <programlisting>
<![CDATA[
dlg = .ASimpleDialog~new("ASimpleDialog.rc", IDD_DIALOG1, dlgData.,"ASimpleDialog.h" )
ret = dlg~execute("SHOWTOP", IDI_DLG_OOREXX)
]]>
</programlisting>The first parameter of the dialog creation statement is the name of the
.rc file, and the second the symbolic ID of the dialog as defined in that file. The third
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
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 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 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
refer to the edit control. However, from a program comprehensibility point of view, it is not
good practice to mix symbolic and numeric resource IDs in the same program. Further, it is
generally held that using only symbolic IDs is best practice. </para>
<para>Section (4) of the code analyzes the user's input. Finally, section (5) displays a message box
to inform the user of the results. </para>
<para>In order to illustrate the same function using <computeroutput>.ResDialog</computeroutput> the
program <computeroutput>ASimpleDialog2.rex</computeroutput> is included in the
<computeroutput>samples\DlgData</computeroutput> folder together with its *.dll file. </para>
<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 ooDialog 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
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>