33 extensible application. The project separates code and data, and uses a form |
33 extensible application. The project separates code and data, and uses a form |
34 of the <xref href="http://wiki.forum.nokia.com/index.php/Design_Patterns_in_Symbian.dita#http://wiki.forum.nokia.com/index.php/Design_Patterns_in_Symbian/Model-View-Control_Pattern">model |
34 of the <xref href="http://wiki.forum.nokia.com/index.php/Design_Patterns_in_Symbian.dita#http://wiki.forum.nokia.com/index.php/Design_Patterns_in_Symbian/Model-View-Control_Pattern">model |
35 view controller pattern</xref> for structuring your code. The application |
35 view controller pattern</xref> for structuring your code. The application |
36 already reacts to system events and contains everything that is required for |
36 already reacts to system events and contains everything that is required for |
37 localization. </p><p/><p><b>What are the directories of a project?</b><fig id="GUID-898488F8-5CF9-4A01-95F8-45E2C5D2E501"> |
37 localization. </p><p/><p><b>What are the directories of a project?</b><fig id="GUID-898488F8-5CF9-4A01-95F8-45E2C5D2E501"> |
38 <image href="GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e4376_href.png" placement="inline"/> |
38 <image href="GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e2166_href.png" placement="inline"/> |
39 </fig></p><p/><b>\group</b><ul> |
39 </fig></p><p/><b>\group</b><ul> |
40 <li><p><b>bld.inf</b>: Component-definition file. This specifies the <codeph>mmp</codeph> files |
40 <li><p><b>bld.inf</b>: Component-definition file. This specifies the <codeph>mmp</codeph> files |
41 that belong to your component, any shared header files that it exports, and |
41 that belong to your component, any shared header files that it exports, and |
42 the default build targets (e.g. GCCE, WINSCW).</p><ul> |
42 the default build targets (e.g. GCCE, WINSCW).</p><ul> |
43 <li><p><codeph>Bld.inf</codeph> is used to generate the makefiles and <codeph>abld.bat</codeph> used |
43 <li><p><codeph>Bld.inf</codeph> is used to generate the makefiles and <codeph>abld.bat</codeph> used |
75 which corresponds to the view in the traditional model view controller pattern.</p></li> |
75 which corresponds to the view in the traditional model view controller pattern.</p></li> |
76 <li><p><b>HelloWorldContainer.cpp</b>: Contains the UI elements that should |
76 <li><p><b>HelloWorldContainer.cpp</b>: Contains the UI elements that should |
77 be displayed by the view. Therefore, the ContainerView and the Container usually |
77 be displayed by the view. Therefore, the ContainerView and the Container usually |
78 have a very strong relationship. </p></li> |
78 have a very strong relationship. </p></li> |
79 </ul><p>During start-up, one class instance creates the next:</p><fig id="GUID-2A3EE3C2-3515-4217-BCB3-182A01936898"> |
79 </ul><p>During start-up, one class instance creates the next:</p><fig id="GUID-2A3EE3C2-3515-4217-BCB3-182A01936898"> |
80 <image href="GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e4482_href.png" placement="inline"/> |
80 <image href="GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e2272_href.png" placement="inline"/> |
81 </fig><p/><p><b>\inc</b></p><ul> |
81 </fig><p/><p><b>\inc</b></p><ul> |
82 <li><p><b>HelloWorldApplication.h</b>, <b>HelloWorldDocument.h</b>, <b>HelloWorldAppUi.h</b>, <b>HelloWorldContainerView.h</b>, <b>HelloWorldContainer.h</b>: Header files corresponding to each of the main source files above. </p></li> |
82 <li><p><b>HelloWorldApplication.h</b>, <b>HelloWorldDocument.h</b>, <b>HelloWorldAppUi.h</b>, <b>HelloWorldContainerView.h</b>, <b>HelloWorldContainer.h</b>: Header files corresponding to each of the main source files above. </p></li> |
83 <li><p><b>HelloWorld.hrh</b>: UIDs/identifiers for UI elements including views. |
83 <li><p><b>HelloWorld.hrh</b>: UIDs/identifiers for UI elements including views. |
84 These are shared between the resource file definitions for UI elements and |
84 These are shared between the resource file definitions for UI elements and |
85 the source code command handlers.</p></li> |
85 the source code command handlers.</p></li> |
135 find. </p><p/><note>If you're working offline you can also search for documentation |
135 find. </p><p/><note>If you're working offline you can also search for documentation |
136 in the SDK. <b>Start</b> menu: <b>Start - S60 Developer Tools - 5th Edition |
136 in the SDK. <b>Start</b> menu: <b>Start - S60 Developer Tools - 5th Edition |
137 SDK, v<i>1.0</i> - SDK Documentation</b></note><p>Right at the top of the |
137 SDK, v<i>1.0</i> - SDK Documentation</b></note><p>Right at the top of the |
138 reference page you will see that the header file we need to use is <codeph>FBS.H</codeph> and |
138 reference page you will see that the header file we need to use is <codeph>FBS.H</codeph> and |
139 the library we need to link against is called <codeph>fbscli.lib</codeph>. </p><fig id="GUID-23B3B7CF-E676-4FBC-8B26-E7B88764781C"> |
139 the library we need to link against is called <codeph>fbscli.lib</codeph>. </p><fig id="GUID-23B3B7CF-E676-4FBC-8B26-E7B88764781C"> |
140 <image href="GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e4680_href.png" placement="inline"/> |
140 <image href="GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e2470_href.png" placement="inline"/> |
141 </fig><p>This class is capable of storing a bitmap. It's also possible to |
141 </fig><p>This class is capable of storing a bitmap. It's also possible to |
142 get direct access to the bitmap data. However for more convenient methods |
142 get direct access to the bitmap data. However for more convenient methods |
143 of drawing we will work through a drawing device and context. </p><p>To |
143 of drawing we will work through a drawing device and context. </p><p>To |
144 find out more about bitmaps, contexts and drawing functions, <xref href="http://developer.symbian.org/search/search_results.php?txtSearch=bitmaps&site=sdl_collection.dita">Search for ‘bitmaps’</xref> in the documentation, and go to the page <b>Bitmaps |
144 find out more about bitmaps, contexts and drawing functions, <xref href="http://developer.symbian.org/search/search_results.php?txtSearch=bitmaps&site=sdl_collection.dita">Search for ‘bitmaps’</xref> in the documentation, and go to the page <b>Bitmaps |
145 in Using Bitmaps</b>, or <b>Using Bitmaps in Using Graphics Device Interfaces</b>. |
145 in Using Bitmaps</b>, or <b>Using Bitmaps in Using Graphics Device Interfaces</b>. |
157 already in the list, so we don’t need to add it. However <codeph>bitgdi.lib</codeph> is |
157 already in the list, so we don’t need to add it. However <codeph>bitgdi.lib</codeph> is |
158 missing. </p><note>There are more libraries in the list than are used by our |
158 missing. </p><note>There are more libraries in the list than are used by our |
159 project (added by the wizard!). These cause no harm so we choose not to remove |
159 project (added by the wizard!). These cause no harm so we choose not to remove |
160 them.</note><p>Click on the <b>Add</b> button. Search for <codeph>bitgdi.lib</codeph> in |
160 them.</note><p>Click on the <b>Add</b> button. Search for <codeph>bitgdi.lib</codeph> in |
161 the list and add it to the <b>Libraries</b> list. </p><fig id="GUID-7D1E15B4-5157-4F48-9084-6DDBD6EE0208"> |
161 the list and add it to the <b>Libraries</b> list. </p><fig id="GUID-7D1E15B4-5157-4F48-9084-6DDBD6EE0208"> |
162 <image href="GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e4758_href.png" placement="inline"/> |
162 <image href="GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e2548_href.png" placement="inline"/> |
163 </fig><p>When you’re finished, make sure that both libraries are in the <b>Libraries</b> list. |
163 </fig><p>When you’re finished, make sure that both libraries are in the <b>Libraries</b> list. |
164 </p><p>When you compile your application again, Carbide.c++ will detect |
164 </p><p>When you compile your application again, Carbide.c++ will detect |
165 the changes in the .mmp file and ask you what to do. Click on <b>Compile and |
165 the changes in the .mmp file and ask you what to do. Click on <b>Compile and |
166 Link</b> to update the project with the changes we have made to the <codeph>.mmp</codeph> file. <fig id="GUID-77F781CD-A2EF-4489-BAE2-EB283057670E"> |
166 Link</b> to update the project with the changes we have made to the <codeph>.mmp</codeph> file. <fig id="GUID-77F781CD-A2EF-4489-BAE2-EB283057670E"> |
167 <image href="GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e4775_href.png" placement="inline"/> |
167 <image href="GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e2565_href.png" placement="inline"/> |
168 </fig></p></section> |
168 </fig></p></section> |
169 <section id="GUID-F2A4FC0F-8C67-4151-8BD2-808FCEDD121F"><title> Creating Bitmaps</title><p>Now |
169 <section id="GUID-F2A4FC0F-8C67-4151-8BD2-808FCEDD121F"><title> Creating Bitmaps</title><p>Now |
170 the libraries have been added, we can use the bitmap classes in our project. |
170 the libraries have been added, we can use the bitmap classes in our project. |
171 Open the file <codeph>HelloWorldContainer.h</codeph> and add the following |
171 Open the file <codeph>HelloWorldContainer.h</codeph> and add the following |
172 include statements: </p><codeblock xml:space="preserve">#include <fbs.h> |
172 include statements: </p><codeblock xml:space="preserve">#include <fbs.h> |
330 system wants the contents of the container to be redrawn. Therefore, we need |
330 system wants the contents of the container to be redrawn. Therefore, we need |
331 to add the following line of code to the end of the <codeph>Draw()</codeph> method, |
331 to add the following line of code to the end of the <codeph>Draw()</codeph> method, |
332 which copies the bitmap to the top left of the graphics context of the screen: </p><codeph>gc.BitBlt(TPoint(0, |
332 which copies the bitmap to the top left of the graphics context of the screen: </p><codeph>gc.BitBlt(TPoint(0, |
333 0), iBitmap);</codeph><p>Now compile the project. It should already work – |
333 0), iBitmap);</codeph><p>Now compile the project. It should already work – |
334 you can draw red lines by just clicking inside the main pane of the emulator! </p><fig id="GUID-CFD29EE4-464B-498C-80F5-493847DE0AEE"> |
334 you can draw red lines by just clicking inside the main pane of the emulator! </p><fig id="GUID-CFD29EE4-464B-498C-80F5-493847DE0AEE"> |
335 <image href="GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e5055_href.png" placement="inline"/> |
335 <image href="GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e2845_href.png" placement="inline"/> |
336 </fig></section> |
336 </fig></section> |
337 <section id="GUID-8DC096A0-807D-437C-9A96-ABAFE2AF7F26"><title> Defining |
337 <section id="GUID-8DC096A0-807D-437C-9A96-ABAFE2AF7F26"><title> Defining |
338 a Menu </title><p>The application would be improved if the user could clear |
338 a Menu </title><p>The application would be improved if the user could clear |
339 the drawing during use, rather than having to restart it. This section shows |
339 the drawing during use, rather than having to restart it. This section shows |
340 how you add and handle menu items to provide this functionality, and to exit |
340 how you add and handle menu items to provide this functionality, and to exit |
341 the application Open the <codeph>HelloWorldContainer.uidesign</codeph> document. |
341 the application Open the <codeph>HelloWorldContainer.uidesign</codeph> document. |
342 You can find it in the root folder of your project in the <b>Project Explorer</b> or |
342 You can find it in the root folder of your project in the <b>Project Explorer</b> or |
343 in the <b>UI Designs</b> folder of the Symbian Project Navigator. </p><p>Click |
343 in the <b>UI Designs</b> folder of the Symbian Project Navigator. </p><p>Click |
344 on the <b>Options</b> menu item below the UI design to reveal the menu. As |
344 on the <b>Options</b> menu item below the UI design to reveal the menu. As |
345 indicated, you simply need to click on the empty menu item and start typing. </p><fig id="GUID-96D944A2-87C5-4530-AB0C-580C3277285D"> |
345 indicated, you simply need to click on the empty menu item and start typing. </p><fig id="GUID-96D944A2-87C5-4530-AB0C-580C3277285D"> |
346 <image href="GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e5079_href.png" placement="inline"/> |
346 <image href="GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e2869_href.png" placement="inline"/> |
347 </fig><p>Add two menu items – <b>Clear</b> (for clearing the image) and <b>Exit</b> (for |
347 </fig><p>Add two menu items – <b>Clear</b> (for clearing the image) and <b>Exit</b> (for |
348 closing the application). </p><p>Then click once on the Exit menu item |
348 closing the application). </p><p>Then click once on the Exit menu item |
349 to select it. Go to the <b>Behavior</b> group of the <b>Properties</b> window |
349 to select it. Go to the <b>Behavior</b> group of the <b>Properties</b> window |
350 and change the command ID to <codeph>EAknCmdExit</codeph> (this is available |
350 and change the command ID to <codeph>EAknCmdExit</codeph> (this is available |
351 in the drop-down list). This command will also be sent to your application |
351 in the drop-down list). This command will also be sent to your application |
352 if the operating system wants to shut it down, for example, when the phone |
352 if the operating system wants to shut it down, for example, when the phone |
353 does not have enough memory left. Therefore, it is necessary that every application |
353 does not have enough memory left. Therefore, it is necessary that every application |
354 always responds to this event and instantly shuts the application down. It |
354 always responds to this event and instantly shuts the application down. It |
355 is already handled by the basic application that the Carbide.c++ wizard generated |
355 is already handled by the basic application that the Carbide.c++ wizard generated |
356 for you; you don’t need to implement the command handling for this event yourself. </p><fig id="GUID-8FD2973F-23FF-4734-AE16-CA39C02C7DE5"> |
356 for you; you don’t need to implement the command handling for this event yourself. </p><fig id="GUID-8FD2973F-23FF-4734-AE16-CA39C02C7DE5"> |
357 <image href="GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e5102_href.png" placement="inline"/> |
357 <image href="GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e2892_href.png" placement="inline"/> |
358 </fig><p>If you try your application now, you will see that the Exit menu |
358 </fig><p>If you try your application now, you will see that the Exit menu |
359 item already works. </p><p/><p><b>Tip</b></p><p> When testing the application, |
359 item already works. </p><p/><p><b>Tip</b></p><p> When testing the application, |
360 always quit your application using the <b>Exit</b> command (rather than just |
360 always quit your application using the <b>Exit</b> command (rather than just |
361 closing the emulator). The application environment will then automatically |
361 closing the emulator). The application environment will then automatically |
362 check for memory leaks. If you just shut down the emulator you may not discover |
362 check for memory leaks. If you just shut down the emulator you may not discover |
372 called <codeph>HandleClearMenuItemSelectedL()</codeph> – a more convenient |
372 called <codeph>HandleClearMenuItemSelectedL()</codeph> – a more convenient |
373 place to put your command-handling code than directly in a big <codeph>HandleCommandL()</codeph> method |
373 place to put your command-handling code than directly in a big <codeph>HandleCommandL()</codeph> method |
374 that receives all commands. The auto-generated source code therefore calls |
374 that receives all commands. The auto-generated source code therefore calls |
375 the new extra method from within <codeph>HandleCommandL()</codeph> (take a |
375 the new extra method from within <codeph>HandleCommandL()</codeph> (take a |
376 look at that method to see what really happens). </p><fig id="GUID-8E944FEE-EFDF-4AFE-BEB8-F3B216B91A98"> |
376 look at that method to see what really happens). </p><fig id="GUID-8E944FEE-EFDF-4AFE-BEB8-F3B216B91A98"> |
377 <image href="GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e5146_href.png" placement="inline"/> |
377 <image href="GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e2936_href.png" placement="inline"/> |
378 </fig><p>Now, we only need to tell the container that it should clear its |
378 </fig><p>Now, we only need to tell the container that it should clear its |
379 bitmap buffer. To do this, create a new public method in the container: </p><codeblock xml:space="preserve">void CHelloWorldContainer::ClearDrawing() |
379 bitmap buffer. To do this, create a new public method in the container: </p><codeblock xml:space="preserve">void CHelloWorldContainer::ClearDrawing() |
380 { |
380 { |
381 iBmpGc->Clear(); |
381 iBmpGc->Clear(); |
382 DrawDeferred(); |
382 DrawDeferred(); |
405 Other Examples</b></p><p>The S60 SDK itself installs many examples; additional |
405 Other Examples</b></p><p>The S60 SDK itself installs many examples; additional |
406 applications can be downloaded from the developer.symbian.org and Forum Nokia |
406 applications can be downloaded from the developer.symbian.org and Forum Nokia |
407 (see the Related Info section for more information). To import ready-made |
407 (see the Related Info section for more information). To import ready-made |
408 applications in Carbide.c++, go to <b>File | Import</b>. In the following |
408 applications in Carbide.c++, go to <b>File | Import</b>. In the following |
409 dialog, select <b>Symbian OS Bld.inf file</b> and click <b>Next</b>. </p><fig id="GUID-8E8F4507-70E7-496C-AE4D-16DAD8146ABA"> |
409 dialog, select <b>Symbian OS Bld.inf file</b> and click <b>Next</b>. </p><fig id="GUID-8E8F4507-70E7-496C-AE4D-16DAD8146ABA"> |
410 <image href="GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e5208_href.png" placement="inline"/> |
410 <image href="GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e2998_href.png" placement="inline"/> |
411 </fig><p/><p>Now, click <b>Browse</b> and navigate to the <codeph>bld.inf</codeph> file |
411 </fig><p/><p>Now, click <b>Browse</b> and navigate to the <codeph>bld.inf</codeph> file |
412 of the project you want to import. It’s usually stored in the <codeph>/group/</codeph> subfolder |
412 of the project you want to import. It’s usually stored in the <codeph>/group/</codeph> subfolder |
413 of the project. </p><fig id="GUID-B682943D-10EE-4DC8-B510-7C2D54C536EE"> |
413 of the project. </p><fig id="GUID-B682943D-10EE-4DC8-B510-7C2D54C536EE"> |
414 <image href="GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e5224_href.png" placement="inline"/> |
414 <image href="GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e3014_href.png" placement="inline"/> |
415 </fig><p>In the following step, select which SDKs you would like to use. The |
415 </fig><p>In the following step, select which SDKs you would like to use. The |
416 same considerations as those explained when creating your Hello World application |
416 same considerations as those explained when creating your Hello World application |
417 apply. </p><fig id="GUID-5A381CA4-CCE0-4359-8F02-697AEDA72BDE"> |
417 apply. </p><fig id="GUID-5A381CA4-CCE0-4359-8F02-697AEDA72BDE"> |
418 <image href="GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e5230_href.png" placement="inline"/> |
418 <image href="GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e3020_href.png" placement="inline"/> |
419 </fig><p>You can usually accept the default values for the next step and let |
419 </fig><p>You can usually accept the default values for the next step and let |
420 the wizard import everything. </p><p>In the last step, you have to define |
420 the wizard import everything. </p><p>In the last step, you have to define |
421 the <b>Project Properties</b>. In most cases, you can leave the default values. </p><fig id="GUID-1AB6D789-9407-4AB0-8F52-B1138DE063BD"> |
421 the <b>Project Properties</b>. In most cases, you can leave the default values. </p><fig id="GUID-1AB6D789-9407-4AB0-8F52-B1138DE063BD"> |
422 <image href="GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e5241_href.png" placement="inline"/> |
422 <image href="GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e3031_href.png" placement="inline"/> |
423 </fig><p>Afterwards, the project is imported and you can start working. The |
423 </fig><p>Afterwards, the project is imported and you can start working. The |
424 project contents will not be copied to the current Carbide.c++ workspace, |
424 project contents will not be copied to the current Carbide.c++ workspace, |
425 so you will work directly on the original directory and the original files. |
425 so you will work directly on the original directory and the original files. |
426 Copy the project to a different directory first if you want to keep the original |
426 Copy the project to a different directory first if you want to keep the original |
427 project or example in its original state – for example, into the workspace |
427 project or example in its original state – for example, into the workspace |