source: branches/ia32/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html

Last change on this file was 8372, checked in by R. Matthew Emerson, 17 years ago

Merged changes 7685:8261 from branches/1.1/ccl.
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
122 the View: Building the User Interface</a>. Read
123 the introduction to
124nibfiles, and follow the instructions to create the Currency Converter
125interface. (Remember that when the tutorial tells you to open and edit
126"MainMenu.nib", you will instead open and edit your
127"CurrencyConverter.nib".) When you reach the end of the section
128called <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
129 the Interface</a>, and move on to the short section afterward
130 called <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 Next</a>,
131 you are done creating the interface for your
132application. Save your nibfile and continue with the next section.</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 instaces
183 of these two classes in the nibfile, so that launching the
184 application creates these instances and the connections between them
185 and the rest of the user interface.</p>
186
187<div class="section-head">
188 <h2>Create Instances of Custom Classes</h2>
189</div>
190
191<p>In InterfaceBuilder's Library window, select the Cocoa Objects and
192 Controllers view:</p>
193
194 <div class="inline-image">
195 <img src="../images/ibwin-leopard3.jpg"alt=""
196 border='0'/>
197 </div>
198
199<p>Drag an Object from the Library window and drop it into the main
200 CurrencyConverter window:</p>
201
202 <div class="inline-image">
203 <img src="../images/ibwin-leopard4.jpg"alt=""
204 border='0'/>
205 </div>
206
207<p>Now tell InterfaceBuilder the name of the new object's class. With
208 the Object icon selected in the main CurrencyConverter window,
209 choose the Identity tab of the Inspector. At the top of the
210 Identity view is a "Class" field; type the name of your custom
211 class (in this case, "Converter") into the "Class" field and save
212 the nibfile:</p>
213
214 <div class="inline-image">
215 <img src="../images/ibwin-leopard5.jpg"alt=""
216 border='0'/>
217 </div>
218
219<p>Repeat the previous steps to create an instance of the
220 ConverterController class: drag an "Object" icon and drop it in the
221 main CurrencyConverter window. Then, change the name of the
222 Object's class to "ConverterController".</p>
223
224<p>That's all it takes to add an instance of a custom class to the
225 nibfile. We do still have to add the names of instance variables and
226 actions, and we need to create the connections between the
227 instances.</p>
228
229<div class="section-head">
230 <h2>Add Outlets and Actions</h2>
231</div>
232
233<p>Now, using the "+" button below the "Class Outlets" section of the
234 Inspector, add outlets to the ConverterController class. The
235 outlets you need to add are named "amountField", "converter",
236 "dollarField", and "rateField".</p>
237
238 <div class="inline-image">
239 <img src="../images/ibwin-leopard6.jpg"alt=""
240 border='0'/>
241 </div>
242
243<p>We'll connect each of the "field" outlets to one of the text
244 fields in the CurrencyConverter UI, and we'll connect the
245 "converter" outlet to the Converter instance that we created
246 before. When the application launches, it creates the Converter and
247 ConverterController instances and establishes the connections that
248 we specify in the nibfile.</p>
249
250
251<p>First, though, we need to tell the nibfile about actions as well as
252 outlets. With the "ConverterController" instance selected, use the
253 "+" button below the "Class Actions" section to add a new
254 action. Name the action "convert:":</p>
255
256 <div class="inline-image">
257 <img src="../images/ibwin-leopard7.jpg"alt=""
258 border='0'/>
259 </div>
260
261<p>In this application, the "convert:" action is the only action
262 defined for the user interface, so we are done with actions now. In
263 more complex applications you may need to define many actions and
264 outlets.</p>
265
266<p>Now we'll connect outlets to objects and actions.</p>
267
268<div class="section-head">
269 <h2>Add Connections</h2>
270</div>
271
272<p>InterfaceBuilder enables you to connect objects by
273 "Control-dragging" from one to another. To "Control-drag", you hold
274 down the Control key while dragging from one object to the next.</p>
275
276<p>Select the "ConverterController" instance in the nibfile's main
277 window, and Control-drag a connection to the "Exchange rate" text
278 field in the application's main window. (Be sure to connect to the
279 text field, not to its label!) When you release the mouse button,
280 InterfaceBuilder pops up a menu that lists the available
281 outlets. Choose "rateField" from the menu. The "rateField" outlet of
282 the "ConverterController" instance is now connected to the "Exchange
283 rate" text field.</p>
284
285<p>Repeat the same steps for the "Dollars" field and the "Amount"
286 field, connecting them to the "dollarField" and "amountField"
287 outlets, respectively.</p>
288
289<p>Finally, Control-drag a connection from the "ConverterController"
290 instance to the "Converter" instance. Choose "converter" from the
291 popup menu to connect the "converter" field of the
292 "ConverterController" instance to the "Converter" instance.</p>
293
294<p>To confirm that the connections are correct, you can use the
295 Connections view in the inspector. With the "ConverterController"
296 instance selected, click the blue arrow icon at the top of the
297 Inspector window to display connections. You should see a list of
298 outlets and the types of objects they are connected to:</p>
299
300 <div class="inline-image">
301 <img src="../images/ibwin-leopard8.jpg"alt=""
302 border='0'/>
303 </div>
304
305<p>We need to add one more connection: from the "Convert" button in
306 the application window to the "ConverterController"
307 instance. Control drag a connection from the "Convert" button in the
308 application window to the "ConverterController" instance in the
309 nibfile's main window. InterfaceBuilder pops up a menu; choose the
310 "convert:" action from the menu to connect the button to the
311 action.</p>
312
313<p>The nibfile now contains descriptions of the needed cusstom
314 classes and their connections. You can continue with the next
315 section, which explains how to write the Lisp code that implements
316 the application's behavior.</p>
317
318 <div class="nav">
319 <p><a href="../../HOWTO.html">start</a>|<a href="making_project.html">previous</a>|<a href="create_lisp.html">next</a></p>
320 </div>
321
322 </body>
323</html>
324
Note: See TracBrowser for help on using the repository browser.