source: trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html @ 8013

Last change on this file since 8013 was 8013, checked in by mikel, 13 years ago

added final text and pictures to Tiger version of IB instructions for Currency Converter HOWTO

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.