examples/S60CppExamples/helloworldbasic/doc/index.html

00001 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
00002 <html>
00003 
00004 <head>
00005 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
00006 <title>Hello World Basic Example</title>
00007 <link href="style.css" rel="stylesheet" type="text/css">
00008 </head>
00009 
00010 <table border="0" width="100%" height="8" bgcolor="#eeeeee">
00011 <tr> <td width="100%" height="1"><b><font size="2" color="#000000" face="Arial, Helvetica, sans-serif"><strong><a name=Top></a>
00012 S60 5th Edition SDK </strong></font></b><br><i>Example Applications Guide</i></td></tr> </table>
00013 <!-- Generated by Doxygen 1.4.5 -->
00014 <div class="tabs">
00015   <ul>
00016     <li id="current"><a href="index.html"><span>Main&nbsp;Page</span></a></li>
00017     <li><a href="annotated.html"><span>Classes</span></a></li>
00018     <li><a href="files.html"><span>Files</span></a></li>
00019   </ul></div>
00020 <h1>Hello World Basic Example</h1>
00021 <p>
00022 <a class="el" href="index.html#Intro_sec">1. About this Example</a> <br>
00023 <a class="el" href="index.html#Arch_sec">2. Architecture</a> <br>
00024 <a class="el" href="index.html#Design_sec">3. Design and Implementation</a><p>
00025 <hr>
00026 <h2><a class="anchor" name="Intro_sec">
00027 1. About this Example</a></h2>
00028 The Hello World Basic example demonstrates how to create a simple interactive application on Symbian OS. Although the program described here basically only displays a simple string, it can be easily adapted to make much larger applications.<p>
00029 Hello World Basic application - in addition to its evident purpose to print "Hello World!" to the screen - also demonstrates displaying text with Information Note and on to the background, loading strings with the help of StringLoader, writing to and reading from a file and use of dialog to inquire user input.<p>
00030 Furthermore, Hello World Basic application is also localized to a few different languages.<h3><a class="anchor" name="Sub11">
00031 1.1. APIs demonstrated</a></h3>
00032 <ul>
00033 <li>StringLoader</li><li>RFs, RFile, RFileWriteStream and RFileReadStream</li><li>CAknInformationNote</li><li>CAknTextQueryDialog</li></ul>
00034 <h3><a class="anchor" name="Sub12">
00035 1.2. Prerequisites</a></h3>
00036 None.<p>
00037 <hr>
00038 <h2><a class="anchor" name="Arch_sec">
00039 2. Architecture</a></h2>
00040 HelloWorld follows traditional Symbian OS Control-based architecture.<p>
00041 <hr>
00042 <h2><a class="anchor" name="Design_sec">
00043 3. Design and Implementation</a></h2>
00044 <h3><a class="anchor" name="Sub31">
00045 3.1 Capabilities</a></h3>
00046 Hello World application does not require any capabilities. The program capabilities are defined in <a class="el" href="helloworldbasic_8mmp-source.html">helloworldbasic.mmp</a> file: CAPABILITY NONE.<h3><a class="anchor" name="Sub32">
00047 3.2 ScalableUI</a></h3>
00048 The program takes screen parameters in the start of the application and works with all screen modes. The program supports changing the screen layout while the program is running. Note that this support must be coded in the application and this code resides in the <a class="el" href="class_c_hello_world_basic_app_view.html#9f9bb5a2110532e2f2909eaefb44d36a">CHelloWorldBasicAppView::SizeChanged()</a> method.<h3><a class="anchor" name="Sub33">
00049 3.3 Static structure</a></h3>
00050 All the classes are derived from CBase. CBase has a number of useful features: it initialises all member data to zero, it has a virtual destructor, and it implements support for the Symbian OS cleanup stack.<h3><a class="anchor" name="Sub34">
00051 3.4 Launch sequence and command handling</a></h3>
00052 This section explains the sequence of interactions that occur on the objects described in the last section when the application is run and the user selects the Hello menu option. The following sections describe the steps in more detail.<p>
00053 <ol type=1>
00054 <li>The application is launched, the framework loads the application EXE and the E32Main() method implemented in <a class="el" href="helloworldbasic_8cpp-source.html">helloworldbasic.cpp</a> is called. Read more from <a class="el" href="index.html#Sub341">3.4.1 Creating the Application object</a>. <br>
00055 <br>
00056 </li><li>E32Main() method calls the function NewApplication(). This creates an instance of the HelloWorldApplication class, and returns a pointer to it. The framework subsequently uses this pointer to complete construction of the application. <br>
00057 <br>
00058 </li><li>The framework calls virtual function AppDllUid() (implementation <a class="el" href="class_c_hello_world_basic_application.html#266a6db7f5728454ee8b7a9c5f517dca">CHelloWorldBasicApplication::AppDllUid</a>) to get the UID of this particular application. The UID is used to, for example, check if an instance of the application is already running, so than the existing instance can be switched to, rather than a new instance created. Read more from <a class="el" href="index.html#Sub342">3.4.2 Getting the application's UID</a>. <br>
00059 <br>
00060 </li><li>The framework calls virtual function CreateDocumentL on the CHelloWorldApplication object: <a class="el" href="class_c_hello_world_basic_application.html#0a048c97a8c1868d0e1e5daf2838bcab">CHelloWorldBasicApplication::CreateDocumentL</a>. This creates an instance of the application Document and returns a pointer to it. This allows the framework to call certain Document methods directly. The Document object is constructed using the Symbian OS construction sequence, using the Document object's static method NewL. Read more from <a class="el" href="index.html#Sub343">3.4.3 Creating the Document object</a>. <br>
00061 <br>
00062 </li><li>The framework calls AppDllUid again, to see if it is necessary to load a file from the filing system. The HelloWorld example does not need to persist any information, and so does not have a file associated with it. <br>
00063 <br>
00064 </li><li>The framework calls the Document object's CreateAppUiL method: <a class="el" href="class_c_hello_world_basic_document.html#0eb34f98d849338274127e28e8c78b4e">CHelloWorldBasicDocument::CreateAppUiL</a>. This creates the AppUI object and returns a pointer to it. <br>
00065 <br>
00066 </li><li>The framework completes the construction of the AppUI object by calling its ConstructL method (<a class="el" href="class_c_hello_world_basic_app_ui.html#9ce34ba0b947863222da3c63d0481044">CHelloWorldBasicAppUi::ConstructL</a>). The fact the framework calls the AppUi object's constructor and ConstructL separately allows the framework to complete any necessary initialisation before construction of the AppUI object is completed. Read more from <a class="el" href="index.html#Sub344">3.4.4 Creating the AppUI and View objects</a>. <br>
00067 <br>
00068 </li><li>The <a class="el" href="class_c_hello_world_basic_app_ui.html#9ce34ba0b947863222da3c63d0481044">CHelloWorldBasicAppUi::ConstructL</a> method first calls the base class's BaseConstructL. This performs such tasks as reading the resource file associated with an application. <br>
00069 <br>
00070 </li><li>The AppUi calls <a class="el" href="class_c_hello_world_basic_app_view.html#5891ab00f23b517058efe213c1febfd2">CHelloWorldBasicAppView::NewL</a> to create the AppView object, using Symbian two phase construction. <br>
00071 <br>
00072 </li><li>The framework calls the Draw (<a class="el" href="class_c_hello_world_basic_app_view.html#67f946ca7848ec78de4961c5bcefdb72">CHelloWorldBasicAppView::Draw</a>) method to draw the view. In this case it will cause a blank screen to be displayed. Read more from <a class="el" href="index.html#Sub345">3.4.5 Redrawing the screen</a>. <div align="center">
00073 <img src="application_started.png" alt="application_started.png">
00074 </div>
00075 </li><li>Whenever the user selects a menu option, <a class="el" href="class_c_hello_world_basic_app_ui.html#a682d228622cea7790645ce10f591242">CHelloWorldBasicAppUi::HandleCommandL</a> is called by the framework and is passed an argument, aCommand, that indicates the command the user selected. The AppUI can then perform whatever actions are required for that particular menu option: <div align="center">
00076 <img src="application_menu.png" alt="application_menu.png">
00077 </div>
00078 <ol type=a>
00079 <li>In case of "Hello", it creates an Information note with the text specified in resource file in it, and displays it.</li><li>In case of "Hello from file", it reads text from Hello.txt -file and displays it in Information note.</li><li>In case of "Hello from edit", it asks text from the user with a dialog and displays it on the screen.</li></ol>
00080 </li></ol>
00081 <h4><a class="anchor" name="Sub341">
00082 3.4.1 Creating the Application object</a></h4>
00083 It is important to note that the NewApplication method is exported by the EXE. This is achieved by adding the EXPORT_C directive before this function in the <a class="el" href="helloworldbasic_8cpp-source.html">helloworldbasic.cpp</a> file. If the EXPORT_C directive is missing, the code will fail to link.<p>
00084 The framework calls the function that is exported by the application at ordinal 1 in the DLL. This means that the first function defined in the DEF-file for an application must be the NewApplication method. By default, the tool chain automatically ensures that this is the case for a Symbian OS application.<p>
00085 Note that this construction does not use the usual Symbian OS new (ELeave) method, but the C++ style new method. This is because a TRAP harness has not been created for the application at this point. If the system is unable to allocate memory for a new instance of the application, the returned instance pointer will be NULL. The framework checks for, and copes with, this possibility.<h4><a class="anchor" name="Sub342">
00086 3.4.2 Getting the application's UID</a></h4>
00087 AppDllUid which gets the application's UID must be present, or the application will fail to link.<h4><a class="anchor" name="Sub343">
00088 3.4.3 Creating the Document object</a></h4>
00089 The Application object is responsible for creating an instance of the Document object. However, it is not required to destroy it. Destruction of the Document object is performed by the framework.<h4><a class="anchor" name="Sub344">
00090 3.4.4 Creating the AppUI and View objects</a></h4>
00091 Note that creation of the AppUi object does not use the Symbian OS two phase construction sequence. Instead the C++ constructor is called, and a pointer to the created instance is returned to the framework. The framework completes construction by calling ConstructL later. Ownership of the AppUI is passed to the framework, and so the Document object is not responsible for destroying it.<h4><a class="anchor" name="Sub345">
00092 3.4.5 Redrawing the screen</a></h4>
00093 The Draw method is called by the framework when the view needs to be redrawn, and contains all the code necessary to draw the view for this application. Note that the framework only calls the Draw method in response to general system events. So, for example, the framework automatically calls Draw when the application is launched, when the Options menu disappears, and if the application regains focus.<p>
00094 The programmer cannot call the Draw method directly, as it requires the system's graphics context to be activated before it is called. Instead, if the programmer wishes to have the screen redrawn, they should call the DrawNow method.<p>
00095 Note that the Draw function cannot leave. This is because the function may be called directly by the framework, and the framework would not know how to handle any errors that might occur. Instead the Draw function must TRAP and handle any errors that might occur.<h4><a class="anchor" name="Sub346">
00096 3.4.6 Handling commands</a></h4>
00097 <a class="el" href="class_c_hello_world_basic_app_ui.html#a682d228622cea7790645ce10f591242">HandleCommandL </a> is called on the AppUi object whenever the user selects a menu option. The argument aCommand indicates the command the user selected. HandleCommandL typically takes the form of a switch statement which invokes different actions according to the value of aCommand.<p>
00098 <b>Handling command "Hello"</b><p>
00099 <ul>
00100 <li>string is loaded from the resource file with StringLoader</li><li>Information note is shown from the descriptor</li></ul>
00101 <p>
00102 <div align="center">
00103 <img src="information_note.png" alt="information_note.png">
00104 </div>
00105 <p>
00106 <b>Handling command "Hello from file"</b><p>
00107 <ul>
00108 <li>connection to the file server is opened with RFs</li><li>RFile is used to open "Hello.txt"-file for reading</li><li>A RFileStream object is created from the file</li><li>An HBufC descriptor is created from the RFileReadStream object</li><li>The descriptor reads from the stream both the length of the data followed by the data. After this descriptor has been read the stream will be positioned at the beginning of the data.</li><li>Information note is shown from the descriptor</li></ul>
00109 <p>
00110 <dl compact><dt><b>Note:</b></dt><dd>"Hello.txt"-file, which is read during the execution of this command, is actually created by the application itself during the execution of <a class="el" href="class_c_hello_world_basic_app_ui.html#9ce34ba0b947863222da3c63d0481044">CHelloWorldBasicAppUi::ConstructL</a>. In other words, it is not an exported ready-made file. The reason for this is that HelloWorld is localized to different languages; and thus during start-up the file is created and the text is written into it with the current language.</dd></dl>
00111 <div align="center">
00112 <img src="japanese_hello.png" alt="japanese_hello.png">
00113 </div>
00114 <p>
00115 <b>Handling command "Hello from edit"</b><p>
00116 <ul>
00117 <li>a string is loaded from the resource file with StringLoader</li><li><a class="el" href="class_c_hello_world_query_dialog.html">CHelloWorldQueryDialog</a> is created and the loaded string is passed to it to be used as default value for input and also a descriptor is passed to store the input given by the user</li><li>no other actions are made, but the text will be displayed in the screen, when the framework calls <a class="el" href="class_c_hello_world_basic_app_view.html#67f946ca7848ec78de4961c5bcefdb72">Draw </a>.</li></ul>
00118 <p>
00119 <div align="center">
00120 <img src="dialog.png" alt="dialog.png">
00121 </div>
00122 <h3><a class="anchor" name="Sub35">
00123 3.5 Handling key events</a></h3>
00124 If the application is required to respond to user keypresses, the AddToStackL method must be called by the AppUi object's ConstructL method, with the AppView object as an argument. This adds the AppView object to the control stack.<p>
00125 If the view is on the control stack, then whenever the user presses a key the OfferKeyEventL method is called. This has arguments that indicate the type of key event (key down, key press or key up) as well as the code of the key pressed.<p>
00126 When the AppUi object is destroyed, the AppView must be removed from the stack. This is done by calling RemoveFromStack in the AppUi object's destructor.<h3><a class="anchor" name="Sub36">
00127 3.6 Localization</a></h3>
00128 HelloWorld application is localized for English, Finnish, Chinese and Japanese. The "main" rls-file HelloWorldBasic.rls includes language specific rls-files, which all each define the same resource strings in specific language. The localized rls-files contain language id in their name (enum TLanguage in e32const.h specifies language identification values), for example: HelloWorldBasic_32.rls.<p>
00129 When localizing to languages, which do not use Western alphabets, such as Chinese or Japanese, a couple of additional steps needs to be taken. As the language cannot be written in ASCII, the language-specific rls-file has to<ul>
00130 <li>be written in UTF-8 format, and</li><li>contain a line CHARACTER_SET UTF8.</li></ul>
00131 <p>
00132 <dl compact><dt><b>Note:</b></dt><dd>Certain editors add some "meta-bytes" into the beginning of file stored in UTF-format. Unfortunately Symbian's resource compiler RCOMP cannot deal with those additional bytes and resource file compilation will fail. It you encounter this, you have to remove those additional bytes with some other editor.</dd></dl>
00133 Furthermore, localization affects mmp- and pkg-files also:<ul>
00134 <li>languages need to be defined in mmp-file. See LANG in <a class="el" href="helloworldbasic_8mmp-source.html">HelloWorldBasic.mmp</a>.</li><li>languages need to be defined in pkg-files and language dependent resource files have to be listed. In addition, most of the strings (e.g. component name) are required to be localized for each defined language. See S60 SDK Help "Package file format" for more detailed information.</li></ul>
00135 <p>
00136 Additionally, HelloWorld application's pkg-files demonstrate two ways to install localized application:<ul>
00137 <li>the language is determined during installation - and only the determined language is installed (the application's language does not change, even if the language in the phone is changed). <br>
00138  HelloWorldBasic_gcce.pkg is made in this fashion.</li><li>the language is determined during installation, but all the supported languages are installed. If the language in the phone changes, the language of the HelloWorld-application changes also, if it supports the new language (English otherwise). <br>
00139  HelloWorldBasic_armv5.pkg is made in this fashion. </li></ul>
00140 <hr>
00141 
00142 <table x-use-null-cells
00143                 style="x-cell-content-align: top;
00144                                 width: 100%;
00145                                 border-spacing: 0px;
00146                                 border-spacing: 0px;"
00147                 cellspacing=0
00148                 width=100%>
00149   <col style="width: 50%;">
00150   <col style="width: 50%;">
00151 
00152   <tr style="x-cell-content-align: top;"
00153         valign=top>
00154   <td style="width: 50%;
00155                         padding-right: 10px;
00156                         padding-left: 10px;
00157                         border-right-style: None;
00158                         border-left-style: None;
00159                         border-top-style: None;
00160                         border-bottom-style: None;"
00161         width=50%>
00162   <p style="font-family: Arial;"><small style="font-size: smaller;">© Nokia 2009</small></td>
00163   <td style="width: 50%;
00164                         padding-right: 10px;
00165                         padding-left: 10px;
00166                         border-top-style: None;
00167                         border-bottom-style: None;
00168                         border-right-style: None;"
00169         width=50%>
00170   <p style="text-align: right; margin-right: -4px;"
00171         align=right><span style="font-weight: bold;"><a href="#Top"
00172                                                                                                         title="Back to top"><img
00173  src="top.gif"
00174         x-maintain-ratio=TRUE
00175         alt="Back to top"
00176         style="border: none;
00177                         width: 18px;
00178                         height: 15px;
00179                         float: none;
00180                         border-style: none;
00181                         border-style: none;"
00182         width=18
00183         height=15
00184         border=0></a></span></td></tr>
00185  </table>
00186 </body>
00187 </html>
00188 

Generated by  doxygen 1.6.2