source: release/1.8/source/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html

Last change on this file was 8441, checked in by mikel, 17 years ago

final edits to currency-converter examples
File size: 14.0 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <title>CurrencyConverter HOWTO</title>
6 <link rel="stylesheet" type="text/css" href="../stylesheets/styles.css" />
7 </head>
8
9 <body>
10
11 <div class="title">
12 <h1>Building the User Interface</h1>
13 </div>
14
15 <div class="body-text">
16 <p>The next step in creating a Lisp version of the currency
17 converter application is to construct the user
18 interface. Apple's
19 tutorial <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/05View/chapter_5_section_1.html#//apple_ref/doc/uid/TP40000863-CH7-SW1">
20 describes in detail</a> how to do this.</p>
21
22<div class="section-head">
23 <h2>Apple's Tutorial</h2>
24</div>
25
26<p>Apple's tutorial explains how to use InterfaceBuilder to create the
27 user interface, and how to use XCode to create project files and
28 write Objective-C code. Our project uses Lisp instead of
29 Objective-C, and does not use XCode project files, so you can skip
30 the part of the tutorial that explains how to use XCode.</p>
31
32<div class="section-head">
33 <h2>Using InterfaceBuilder to Create the UI</h2>
34</div>
35
36 <p>We'll begin by using Apple's InterfaceBuilder application to
37 create a nibfile. The nibfile contains
38 archived versions of the Objective-C objects that define the
39 application's user interface. When you launch an application,
40 Mac OS X uses the archived objects in the nibfile to create the
41 windows and menus you see on the screen. </p>
42
43 <p>Start by locating Apple's InterfaceBuilder application. If
44 you installed Apple's Developer Tools, InterfaceBuilder should
45 be in the folder "/Developer/Applications/":</p>
46
47 <div class="inline-image">
48 <img src="../images/finder-win1.jpg"alt=""
49 border='0'/>
50 </div>
51
52
53 <p class= "note"><strong><em>NOTE:</em></strong> If you have not installed Apple's Developer Tools, you should
54 do that now. You will not be able to build the CurrencyConverter
55 example without them. The Developer Tools are distributed as an
56 optional install with Mac OS X 10.5 ("Leopard"). Look for the
57 "XCode Tools" package in the "Optional Installs" folder on the
58 Mac OS 10.5 install disk.</p>
59
60 <p>Once you have located InterfaceBuilder, double-click to launch
61 the application. InterfaceBuilder presents a window you can use
62 to choose a template for the nibfile you are going to create.</p>
63
64 <div class="inline-image">
65 <img src="../images/ibwin-leopard1.jpg"alt=""
66 border='0'/>
67 </div>
68
69 <p>Click the "Application" icon and then click the "Choose" button to
70 create an application nibfile. InterfaceBuilder creates a new
71 application nibfile, but doesn't immediately save it. The
72 Objective-C objects that represent the new application's
73 interface appear in a new untitled window:</p>
74
75 <div class="inline-image">
76 <img src="../images/ibwin-leopard2.jpg"alt=""
77 border='0'/>
78 </div>
79
80 <p>The intial window and menubar also appear on the screen. The
81 new application's name appears in the menus as
82 "NewApplication". Save the new nibfile into the
83 "currency-converter" folder that you created earlier
84 (on <a href="making_project.html">this
85 page</a>). InterfaceBuilder 3.0 gives you a choice of file
86 formats when you save a new nibfile; use the "NIB 3.x"
87 format&mdash;the "XIB 3.x" format works fine for editing your
88 user interface, but will not work correctly if you try to use it
89 in a working application. Give the new file the name
90 "CurrencyConverter.nib".</p>
91
92 <div class="note">
93 <p><strong><em>NOTE:</em></strong> Most Objective-C application projects use a main
94 nibfile called "MainMenu.nib", and if you use XCode to create
95 a new application project, it creates a nibfile with that
96 name. Apple's CurrencyConverter tutorial assumes that the
97 name of the main nibfile is "MainMenu.nib".</p>
98
99 <p>So, why do we tell you to use a different name? Clozure CL
100 has a main nibfile built into it, whose name is
101 "MainMenu.nib". Normally you don't see it, and don't even
102 need to know that it exists. But the Clozure CL
103 application-building tools create a new application by
104 copying resources from the Clozure CL application, so that
105 your new application has available to it all the built-in
106 Clozure CL tools. We ask you to name your nibfile
107 "CurrencyConverter.nib" so that it can coexist with the
108 Clozure CL main nibfile without causing any problems.</p>
109
110 <p>This difference between a Lisp project and an Objective-C
111 project might be a little confusing at first. Just try to keep
112 in mind that whenever Apple's tutorial refers to the
113 "MainMenu.nib" file, it means the file we have just created
114 and named "CurrencyConverter.nib". In a Clozure CL project,
115 "MainMenu.nib" is the name of the main Lisp nibfile, not your
116 application's main nibfile.</p>
117 </div>
118
119
120<p>Skip straight to the part of Apple's tutorial
121called <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/05View/chapter_5_section_1.html#//apple_ref/doc/uid/TP40000863-CH7-SW1">Defining
122the View: Building the User Interface</a>. Read the introduction to
123nibfiles, and follow the instructions to create the Currency Converter
124interface. (Remember that when the tutorial tells you to open and edit
125"MainMenu.nib", you will instead open and edit your
126"CurrencyConverter.nib".) When you reach the end of the section
127called <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/05View/chapter_5_section_5.html#//apple_ref/doc/uid/TP40000863-CH7-DontLinkElementID_38">Test
128the Interface</a>, and move on to the short section afterward
129called <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/05View/chapter_5_section_6.html#//apple_ref/doc/uid/TP40000863-CH7-DontLinkElementID_39">What's
130Next</a>, you are done creating the interface for your
131application. Save your nibfile and continue with the next section of
132this HOWTO.</p>
133
134<div class="section-head">
135 <h2>What if You Need to Use InterfaceBuilder 2.x?</h2>
136</div>
137
138<p>If you are still using Mac OS X 10.4.x ("Tiger"), you can still
139 create a working nibfile and you can still follow the instructions
140 in this HOWTO to create a Cocoa application with Clozure CL. The
141 main obstacle to doing so is that the earlier versions of
142 InterfaceBuilder have a significantly different user interface, and
143 so you may find it hard to follow Apple's tutorial when working with
144 InterfaceBuilder.</p>
145
146<p>If you are working with Mac OS X 10.4.x ("Tiger"), you can
147 look <a href="building_ui_tiger.html">here</a> to find a description
148 of how to build the user interface files with the earlier version of
149 InterfaceBuilder. When you have finished building your user
150 interface, you can continue with the <a href="create_lisp.html">next
151 section</a>, "Creating a Lisp File".</p>
152
153<p>One other thing: if you are using Mac OS X 10.4.x ("Tiger"), you
154 will be able to build Cocoa applications only on PPC Macs. The
155 Clozure CL Objective-C support for Intel systems works only on Mac
156 OS X 10.5.x ("Leopard").</p>
157
158
159<div class="section-head">
160 <h2>Adding Custom Classes to the nibfile</h2>
161</div>
162
163<p>Once the user interface for your application looks right, there is
164 still one important task to complete before you can use it. You must
165 record some information in the nibfile about the classes of the
166 objects, so that the application can create them with the right
167 connections in place.</p>
168
169<p>When you use XCode to write an Objective-C application,
170 InterfaceBuilder can read the Objective-C header files and use the
171 information in them to create descriptions of the classes in the
172 Objective-C code. When the application is written in Lisp,
173 InterfaceBuilder can't read the class descriptions from the code,
174 and so we'll have to manually tell the nibfile about any classes
175 that we use in the user interface.</p>
176
177<p>As you will see in the following sections, we'll use Lisp code to
178 define two Objective-C classes: Converter, and
179 ConverterController. The Converter class implements the method that
180 performs the actual currency conversion for our application; the
181 ConverterController class provides communication between the user
182 interface and the Converter object. We need a way to create
183 instances of these two classes in the nibfile, so that launching the
184 application sets up all the objects correctly.</p>
185
186<div class="section-head">
187 <h2>Create Instances of Custom Classes</h2>
188</div>
189
190<p>In InterfaceBuilder's Library window, select the Cocoa Objects and
191 Controllers view:</p>
192
193 <div class="inline-image">
194 <img src="../images/ibwin-leopard3.jpg"alt=""
195 border='0'/>
196 </div>
197
198<p>Drag an Object from the Library window and drop it into the main
199 CurrencyConverter window:</p>
200
201 <div class="inline-image">
202 <img src="../images/ibwin-leopard4.jpg"alt=""
203 border='0'/>
204 </div>
205
206<p>Now tell InterfaceBuilder the name of the new object's class. With
207 the Object icon selected in the main CurrencyConverter window,
208 choose the Identity tab of the Inspector. At the top of the
209 Identity view is a "Class" field; type the name of your custom
210 class (in this case, "Converter") into the "Class" field and save
211 the nibfile:</p>
212
213 <div class="inline-image">
214 <img src="../images/ibwin-leopard5.jpg"alt=""
215 border='0'/>
216 </div>
217
218<p>Repeat the previous steps to create an instance of the
219 ConverterController class: drag an "Object" icon and drop it in the
220 main CurrencyConverter window. Then, change the name of the
221 Object's class to "ConverterController".</p>
222
223<p>That's all it takes to add an instance of a custom class to the
224 nibfile. We do still have to add the names of instance variables and
225 actions, and we need to create the connections between the
226 instances.</p>
227
228<div class="section-head">
229 <h2>Add Outlets and Actions</h2>
230</div>
231
232<p>Now, using the "+" button below the "Class Outlets" section of the
233 Inspector, add outlets to the ConverterController class. The
234 outlets you need to add are named "amountField", "converter",
235 "dollarField", and "rateField".</p>
236
237 <div class="inline-image">
238 <img src="../images/ibwin-leopard6.jpg"alt=""
239 border='0'/>
240 </div>
241
242<p>We'll connect each of the "field" outlets to one of the text fields
243 in the CurrencyConverter UI, and we'll connect the "converter"
244 outlet to the Converter instance that we created before. When the
245 application launches, it creates the Converter and
246 ConverterController instances and establishes the connections that
247 we've specified in the nibfile.</p>
248
249
250<p>First, though, we need to tell the nibfile about actions as well as
251 outlets. With the "ConverterController" instance selected, use the
252 "+" button below the "Class Actions" section to add a new
253 action. Name the action "convert:":</p>
254
255 <div class="inline-image">
256 <img src="../images/ibwin-leopard7.jpg"alt=""
257 border='0'/>
258 </div>
259
260<p>In this application, the "convert:" action is the only action
261 defined for the user interface, so we are done with actions now. In
262 more complex applications you may need to define many actions and
263 outlets.</p>
264
265<p>Now we'll connect outlets and actions to objects.</p>
266
267<div class="section-head">
268 <h2>Add Connections</h2>
269</div>
270
271<p>InterfaceBuilder enables you to connect objects by
272 "Control-dragging" from one to another. To "Control-drag", you hold
273 down the Control key while dragging from one object to the next.</p>
274
275<p>Select the "ConverterController" instance in the nibfile's main
276 window, and Control-drag a connection to the "Exchange rate" text
277 field in the application's main window. (Be sure to connect to the
278 text field, not to its label!) When you release the mouse button,
279 InterfaceBuilder pops up a menu that lists the available
280 outlets. Choose "rateField" from the menu. The "rateField" outlet of
281 the "ConverterController" instance is now connected to the "Exchange
282 rate" text field.</p>
283
284<p>Repeat the same steps for the "Dollars" field and the "Amount"
285 field, connecting them to the "dollarField" and "amountField"
286 outlets, respectively.</p>
287
288<p>Finally, Control-drag a connection from the "ConverterController"
289 instance to the "Converter" instance. Choose "converter" from the
290 popup menu to connect the "converter" field of the
291 "ConverterController" instance to the "Converter" instance.</p>
292
293<p>To confirm that the connections are correct, you can use the
294 Connections view in the inspector. With the "ConverterController"
295 instance selected, click the blue arrow icon at the top of the
296 Inspector window to display connections. You should see a list of
297 outlets and the types of objects they are connected to:</p>
298
299 <div class="inline-image">
300 <img src="../images/ibwin-leopard8.jpg"alt=""
301 border='0'/>
302 </div>
303
304<p>We need to add one more connection: from the "Convert" button in
305 the application window to the "ConverterController"
306 instance. Control drag a connection from the "Convert" button in the
307 application window to the "ConverterController" instance in the
308 nibfile's main window. InterfaceBuilder pops up a menu; choose the
309 "convert:" action from the menu to connect the button to the
310 action.</p>
311
312<p>The nibfile now contains descriptions of the needed cusstom
313 classes and their connections. You can continue with the next
314 section, which explains how to write the Lisp code that implements
315 the application's behavior.</p>
316
317 <div class="nav">
318 <p><a href="../../HOWTO.html">start</a>|<a href="making_project.html">previous</a>|<a href="create_lisp.html">next</a></p>
319 </div>
320
321 </body>
322</html>
323
Note: See TracBrowser for help on using the repository browser.