Symbian3/PDK/Source/GUID-9BADA8E9-15AA-5867-BF14-DB8C4D9B40A6.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Tue, 30 Mar 2010 11:56:28 +0100
changeset 5 f345bda72bc4
parent 3 46218c8b8afa
child 14 578be2adaf3e
permissions -rw-r--r--
Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     6
<!-- Initial Contributors:
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     7
    Nokia Corporation - initial contribution.
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     8
Contributors: 
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
     9
-->
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    10
<!DOCTYPE concept
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    12
<concept xml:lang="en" id="GUID-9BADA8E9-15AA-5867-BF14-DB8C4D9B40A6"><title>Naming Conventions</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Applications on the Symbian platform use a standard set of conventions to name their classes, structs, variables, functions, macros, enumerations, and constants. This topic explains the meaning of these conventions. </p> <section><title>Class names</title> <p>Most class names are formed with a prefix letter <codeph>C</codeph>, <codeph>T</codeph>, <codeph>R</codeph>, or <codeph>M</codeph>. Briefly, the meaning of these is as follows: </p> <ul><li id="GUID-2F4845E7-26DF-585A-A04B-5FA92C602D5D"><p> <codeph>C</codeph>: heap-allocated classes, that are derived from a base class <codeph>CBase</codeph>  </p> </li> <li id="GUID-1769E8BD-E386-59EE-A631-CB2B998812DB"><p> <codeph>T</codeph>: value classes, that do not own any external object </p> </li> <li id="GUID-69F2347E-9CF6-5E56-9124-4D4D2B6B1620"><p> <codeph>R</codeph>: resource classes, that contain handles to a real resource which is maintained elsewhere </p> </li> <li id="GUID-81D42168-744A-55EF-BFD5-13A2E2609CD9"><p> <codeph>M</codeph>: interface classes, that define abstract protocol definitions that are implemented by derived classes </p> </li> </ul> <p>For a detailed discussion on the meaning of these prefixes, see <xref href="GUID-2458916B-55B2-5E08-A825-4EBDB3503E67.dita">Class types</xref>. </p> <p>Classes that consist solely of static member functions have no prefix letter. Beyond the prefix, the class name is usually a noun that indicates the purpose of the class. </p> </section> <section><title>Struct names</title> <p>Structure types are considered as similar to <codeph>T</codeph> classes, as they should not own external objects, and are normally given names beginning with <codeph>T</codeph> (although some begin with <codeph>S</codeph>). </p> </section> <section><title>Variable names</title> <p>Member variables’ names begin with <codeph>i</codeph>, e.g. <codeph>iMember</codeph>. This makes it easy to check that certain cleanup-related rules are being obeyed. Arguments’ names begin with <codeph>a</codeph>, e.g. <codeph>aControl</codeph> or <codeph>aIndex</codeph>. Local variables’ names have no initial letter. Global variables are usually avoided, but when used, their names begin with a capital letter. </p> <p>The Symbian platform does not use Hungarian or any notation which attempts to include the variable type in its name: such notations are ugly, and become impossible to manage when there are several hundred classes in the system. They are irrelevant anyway: functions are usually so short that it is easy to see the types of variables defined in them, and class browsers provide a quick way to find the types of class members. </p> </section> <section><title>Function names</title> <p>Functions’ names indicate what they do. They are usually verbs. One exception is “getter” functions: for a function which returns the value of a member variable, the function name is usually the name of the variable, without the leading <codeph>i</codeph>: </p> <codeblock id="GUID-D2C3445C-50C9-5C11-8D3B-67DE163C9600" xml:space="preserve">inline RWindow&amp; Window() const { return iWindow; };</codeblock> <p>A corresponding “setter” function would include the word <codeph>Set</codeph>, e.g. <codeph>SetWindow()</codeph>. </p> <p>To terminate functions because of error conditions, the Symbian platform does not use standard C++ exception handling, but its own system called leaving (see <xref href="GUID-E5A83EF3-948B-5729-A2CD-3644E803520B.dita">Cleanup Support Overview</xref>). Any function that might leave has a name ending in <codeph>...L()</codeph>. This makes the fundamental process of checking for errors easier. The <codeph>new (ELeave)</codeph> function might also leave. The fundamental leaving function is <codeph>User::Leave()</codeph>. Any function that contains any of these, and does not trap them, might itself leave, and should be coded with a trailing <codeph>L</codeph> in its name. If a function calls another which might leave, then its name should have the <codeph>L</codeph> suffix also. </p> <p>Associated with the leaving mechanism, is the cleanup stack, which allows memory allocated on the heap to be recovered when a leave occurs. An allocation or construction function which places data on the cleanup stack ends with <codeph>...LC()</codeph>. For instance, many <codeph>new</codeph>, <codeph>PushL()</codeph>, <codeph>ConstructL()</codeph> sequences are encapsulated in a <codeph>NewLC()</codeph> function: </p> <codeblock id="GUID-51A820E0-923C-5626-A791-7FA0E8F6B6AF" xml:space="preserve">CS* s=CS::NewLC(p1, p2);</codeblock> <p>This allocates the object, initialises it, and leaves it on the cleanup stack. This process may leave (if only through the <codeph>PushL()</codeph> !), so such functions always include an <codeph>L</codeph>, and are therefore <codeph>...LC()</codeph>. </p> <p>A function which takes ownership of its object and destroys it has a name ending in <codeph>...D()</codeph>. An example is the UI framework dialog protocol: </p> <codeblock id="GUID-865E8BED-1C1B-5BC7-A92F-1B5DA6885100" xml:space="preserve">CEikDialog* dialog=new (ELeave) CBossSettingsDialog;
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    13
if (dialog-&gt;ExecuteLD(R_BOSS_SETTINGS_DIALOG))
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    14
    {
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    15
    // handle successful settings
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    16
    }</codeblock> <p>The <codeph>ExecuteLD()</codeph> function includes second-phase construction, execution of the dialog and then destruction. </p> </section> <section><title>Macro names</title> <p>Macro names are all capitalised, with underscores to separates words. </p> </section> <section><title>Enumeration names</title> <p>Enumerations are named as follows: </p> <ul><li id="GUID-FFB2E991-CB2B-5F95-BF13-E0019EF0FDD8"><p>as enumerations are types, they have the <codeph>T</codeph> prefix </p> </li> <li id="GUID-9E021588-6989-59D7-93D6-6E6B27A88E45"><p>enumeration members have the prefix <codeph>E</codeph>  </p> </li> <li id="GUID-95C953A3-6E0F-5FE2-B357-D1A470DC92E5"><p>type and members should have a meaningful, unambiguous name </p> </li> </ul> <p>Enumerations should be scoped within the relevant class, so as not to pollute the global name space. </p> <p>An example of the declaration and use of an enumeration is as follows: </p> <codeblock id="GUID-035D6258-29BD-5104-A758-81F0C8098DF2" xml:space="preserve">class TDemo
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    17
    {
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    18
public:
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    19
    enum TShape {EShapeRound, EShapeSquare};
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    20
    };
f345bda72bc4 Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 3
diff changeset
    21
1
25a17d01db0c Addition of the PDK content and example code for Documentation_content according to Feature bug 1607 and bug 1608
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    22
TDemo::TShape shape=TDemo::EShapeSquare;</codeblock> </section> <section><title>Constant names</title> <p>Names of constants have a prefix <codeph>K</codeph>. For example, </p> <codeblock id="GUID-4270AB29-EE1F-5DA4-ADA1-16A8DC43A9FC" xml:space="preserve">const TInt KMaxNameLength=0x20;</codeblock> </section> </conbody></concept>