Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

[r8771]: ooDialog / branches / 4.2.1 / doc / oodguide / en-US / Appendix05.xml Maximize Restore History

Download this file

Appendix05.xml    291 lines (225 with data), 12.2 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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
<?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 05 - The Model-View Framework (MVf) v01-01 20Dec12
A brief overview of the internals of the Model-View Framework (MVF).
Changes:
v01-01 20Dec12: First version.
Notes:
Include overview of ObjectMgr.
-->
<appendix id="apx-mvfinternals">
<title id="mvfinternals.title">Model-View Framework Internals</title>
<indexterm><primary>Model-View Framework</primary><secondary>Internals</secondary></indexterm>
<para>This appendix provides an overview of the internals of the Model-View Framework (MVF.)
It should really be called "Model-View-Data
Framework", since it also encompasses data components; however, historically such frameworks
have omitted the term "data" in their names, and here we lazily conform with precedence. The
following areas are addressed:<itemizedlist>
<listitem>
<para>A brief review of what is meant by "component"</para>
</listitem>
<listitem>
<para>The classes that make up the MVF</para>
</listitem>
<listitem>
<para>Using the MVF </para>
</listitem>
</itemizedlist></para>
<!-- Section 1: Components, Classes, Files and Folders -->
<section><title>Components, Classes, Files, and Folders</title>
<para>A "component", then, is one of three kinds: a Model, View, or Data component. A component
may have more than one class. For example, the "ProductView" component (in the
<computeroutput>Exercise07\Product</computeroutput> folder) consists of three classes:
<computeroutput>ProductView</computeroutput>, <computeroutput>AboutDialog</computeroutput>,
and <computeroutput>HRSpv</computeroutput>. The first of these is the "main" class in the
component, the other two being "subsidiary" classes. <indexterm>
<primary>Business Component</primary>
</indexterm>
<indexterm>
<primary>Main class</primary>
</indexterm>
<indexterm>
<primary>Subsidiary class</primary>
</indexterm>
<indexterm>
<primary/>
</indexterm> This component, together with the ProductModel, ProductListModel,
ProductListView, and ProductData components make up the "Product Business Component". Thus a
"business component" consists of one or more components, each of which has a "main" class and
nought or more subsidiary classes. Thus (by design) a Business Component is a collection of
components that implement all and only a significant business concept. Finally, a business
component is packaged within a folder that bears its name. And components are packaged in .rex
files, Thus the Product business component is the folder
<computeroutput>Product</computeroutput> which contains a number of files, most of them
executables such as <computeroutput>ProductModelsData.rex</computeroutput> which contains the
ProductModel, ProductListModel, and ProductData components. </para>
<para>For each component, one class is made known by name to
<computeroutput>ObjectMgr</computeroutput>. The class will always be the "main" class. </para>
</section>
<!-- Section 2: The Object Manager -->
<section id="app5ObjectMgr"><title>MVF Classes</title>
<indexterm><primary>Object Manager</primary></indexterm>
<para>The Model-View Framework (MVF) manages the components that are assembled to make up an
application. There are two main parts to the MVF: first a management class called the "Object
Manager" (<computeroutput>ObjectMgr.rex</computeroutput>), and secondly a set of superclasses
- <computeroutput>Model</computeroutput>, <computeroutput>GenericFile</computeroutput>, and
three View superclasses <computeroutput>UdView.rex</computeroutput>,
<computeroutput>ResView.rex</computeroutput>, and
<computeroutput>RcView.rex</computeroutput>. The three View superclasses are identical
except for their superclasses - <computeroutput>UserDialog</computeroutput>,
<computeroutput>ResDialog</computeroutput>, and <computeroutput>RcDialog</computeroutput>.
These should properly be mixins rather than different files, and a future version of this
Guide will take this approach. All MVF classes are in the
<computeroutput>Exercise07/Support</computeroutput> folder). </para>
</section>
<section id="mvfinternals-mvfmethods"><title>MVF Methods</title>
<para>
<programlisting>
<![CDATA[
GetComponentId for a Model when neither Model nor Data have been instantiated.
X: getComponentId('PersonModel', 'PA100') --> ObjectMgr
ObjectMgr: newInstance('PA100') --> .PersonModel
.PersonModel: forward class (super) continue --> .Model
.Model: getComponentId('PersonData','The') --> ObjectMgr
ObjectMgr: ...return idPersonData ... .Model
.Model: getRecord('PA100') --> PersonData
(no 'getRecord' method, so call super) --> GenericFile
GenericFile ... return dirData ... .Model
.Model self~new(dirData) - init(dirData) --> PersonModel
PersonModel ... init: store dirData, return self ... .Model
.Model ... return idPersonModel ... ObjectMgr
ObjectMgr ... return idPersonModel ... X
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PersonModel
-----------
::METHOD newInstance CLASS PUBLIC
use strict arg instanceName
forward class (super) continue
modelId = RESULT
return modelId
::METHOD init
expose dirPerson
use strict arg dirPerson
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PersonData
----------
::METHOD newInstance CLASS PUBLIC
-- If first invocation:
personDataId = self~new()
return personDataId
::METHOD init PUBLIC
fileName = "..\samples\person\PersonFile.txt"
columns = 6 -- colums in the Persons "table"
records = self~init:super(fileName, columns)
return self -- MVF
===================================================================
showModel(class-inst) -> ObjectMgr
self~getcreate model
View components: subclass RcView
- newInstance [class method]:
use arg modelInsanceName, rootDlg
dlg = .ModelView~new(rc-file, "IDD_...")
dlg~activate(modelInstancName,rootDlg)
return dlg
- activate
expose modelData
use arg modelInstanceName, rootDlg
forward class (super) continue Required for MVF
modelData = RESULT - personData returned by super
- ('forward' returns any result via 'RESULT'.)
self~popUpAsChild(rootDlg,"SHOWTOP,,icon-resource-id>)
- initDialog
expose modelData
Model components:
- newInstance (class method):
use strict arg instanceName
check id data component is up and running
get component id of data component from objectMgr
send "find(instanceName)" to data component - returns "dirData"
modelId = self~new(dirData)
return modelId
- init (instance Method)
- since no separate setup, 'activate' is same as 'init' so just use 'init'.
Data components: - subclassed from GenericFile
- newInstance (class method):
use strict arg instanceName - instanceName is "The".
dataId = self~new(instanceName)
return dataId
- init
use arg instanceName
filename = "file-name"; columns = num-columns
records = self~init:super(fileName, columns)
]]>
</programlisting>
</para>
</section>
<section id="mvfinternals-classnaming"><title>Class Naming Constraints</title>
<indexterm><primary>MVF</primary><secondary>Class names</secondary></indexterm>
<indexterm><primary>Class naming for the MVF</primary></indexterm>
<para>*** Do we need this here, or is it better in Chap 7, or just a pointer from here to Chap 7?</para>
</section>
<section id="mvfinternals-requireslist"><title>The "Requires List"</title>
<indexterm><primary>RequiresList</primary></indexterm>
<para>An oorexx class that is instantiated from another file must be stated in an oorexx
"requires" statement. However, in the MVF component instantiation (or, to be precise,
instantiation of the main class in a component) is handled by
<computeroutput>ObjectMgr</computeroutput>. This mean that
<computeroutput>ObjectMgr</computeroutput> must contain a <emphasis role="italic"
>::requires</emphasis> statement for each component. However, to avoid changing the
<computeroutput>ObjectMgr.rex</computeroutput> file, a separate file
(<computeroutput>RequiresList.rex</computeroutput> in the
<computeroutput>Exercise07</computeroutput> folder) containing only the desired set of
<emphasis role="italic">::requires</emphasis> statements is used.
<computeroutput>ObjectMgr.rex</computeroutput>calls this file as a routine (<emphasis
role="italic">call "RequiresList.rex"</emphasis>) as its first executable statement. In this
way, additional ooRexx components can be added to the application merely by adding their file
names to this file.</para>
</section>
<section id="mvfinternals-ViewMgr"><title>"The View Manager"</title>
<indexterm><primary>View Manager</primary></indexterm>
<para> The View Manager manages common function to do with views (or dialogs). In this Exercise,
it is used only for offsetting dialogs and ...[*** to be continued ***]. </para>
</section>
</appendix>