in the toolbar so your components show up.The component system makes up the foundation of the UI Designer. It provides components to the UI Designer from component library plugins or user component projects in the current workspace. In the UI Designer, each component is defined by an XML file, an associated set of JavaScript files, images, and sometimes Eclipse extension points.
-Each component defines its related properties, property types, events, rendering, source generation, RSS mapping, editor icon and description. A component also defines its behavior for a specific part of the target program. Each component is typically a single control (e.g. CEikEdwin) or container (e.g. CAknView or CCoeControl), but are sometimes defined for portions of such controls when it is more convenient for implementation, for example individual items of CAknListBox. Components may also refer to instances of C++ classes (like active objects) or transient dialogs (like progress dialogs).
-Components may derive from other components, allowing them to share, override, and augment key parts of another's implementation. However, only single inheritance is supported.
-A component is defined by a unique ID (qualifiedName), which identifies it to other parts of the UI Designer. These are usually dotted names, for example, "com.nokia.sdt.series60.CAknForm". Components in the UI Designer are marked by an SDK vendor and version. Multiple components with the same unique ID may be defined, if each has a different SDK range. One or none will be selected for use in a design based on the baseline SDK selected, allowing the UI Designer to generate source and resources that are compatible with all SDKs in a project. Sometimes, generated source may compensate for SDK differences with #ifdefs, but this is exceedingly rare in practice.
-Component definitions also include their own version, which means changes in component structure may be detected and acted upon by an update mechanism in Carbide.c++. It's important to design components strictly in accordance with the API versions they target. You want to be sure users will have compilable source no matter what SDK or combination of SDK's they select, even if they change build configurations for their project. Note that this means a component will not necessarily be available for all SDKs in use. The UI Designer can deal gracefully with components that are no longer available for a given SDK, but ample warnings are provided to prevent a design from being saved with a missing component.
-The data model represents a design, wherein instances of components (component instances) are stored, along with their associated property settings and event bindings. The model as a whole also contains a shared language string table and source generation metadata. This design is generated into .uidesign files. The .uidesign files can be graphically displayed in the UI Designer editor or textually displayed in a text editor to reveal their generated XML structure.
-The data model remembers the baseline SDK and component versions used for the last save, so it can detect when components are updated or when the related project's build configurations become incompatible with a design. This will prompt the user to take action.
-The baseline SDK associated with a data model is used in conjunction with the component system to form a component set. The set is a collection of components which are valid for that configuration. The newest compatible component is selected for use in a design.
-A UI design only references components by ID. This allows the structure of components to change without the UI design becoming invalid. Aside from the ID, only the names of properties and events are reflected in the design. Even types of properties are ignored and property values are stored as strings. Thus, a component may add or drop properties between versions, or add or drop events, or (within reason) change the types of properties, without rendering the UI design invalid. The data model will retain any properties that were set, even if they disappear from a component, usually allowing for a design to be converted to a newer or older component version without losing information.
-Components may publish a dynamic set of properties based on runtime checks, allowing them to adapt to the requirements of other component instances. The S60 List Box, for example, uses the "style" property to control which properties are available on its child List Item component instances. Since the data model is flexible and retains properties that no longer exist, fields which relate to other styles may be swapped out without losing information. Thus, you can switch a list box from a "double large" style to a "double time" style to a "single text" style and back without losing any list item information.
-When designing a component, it is important to consider how its data will be used and stored in the data model. Design for flexibility, constructing properties that are independent of each other (as much as possible) and which correspond to specific RSS member fields or C++ setter methods; so they may evolve in coordination with the APIs they are targeting. Also split components into pieces when they have a variable number of contained similar items, rather than making complex array properties.
-A data model specifies a display model, which consists of various aspects on how the design is displayed on screen. It controls how the model is converted into a layout for use by the editor and how that layout is rendered into images. For S60, each component provides a bitmap with transparency and these are drawn on top of each other to make the composite screen.
-A component also provides the applicable layout configurations (screen sizes and portrait/landscape orientations), which supply "look and feel" interfaces that abstract layout-dependent colors, points, rectangles, images, flags, and strings into named keys for use by components. This allows components to be written for any current or future layout. New components will need to implement the rendering interface "IVisualAppearance" to draw their contents onto a transparent bitmap, using SWT GC operations. Alternately, initial implementations can provide a static bitmap image to represent the component.
-The editor provides the user interaction with the data model and display model. It coordinates the editor document, palette, properties view, outline view, and events view. The editor's document represents the layout object tree, while the outline view represents the data model. The properties and events views show information for the currently selected item.
-In the editor, the palette shows a filtered view of components available for the UI design. The containers in the model are queried for compatibility with each component (by the IQueryContainment interface) and only valid combinations are shown in the palette. This is not the full set of installed components. Thus, an important first step for developing new components is to understand how containment works and toggle the "Palette filtering" button in the toolbar so your components show up.
The component system makes up the foundation of the UI Designer. It provides components to the UI Designer from component library plugins or user component projects in the current workspace. In the UI Designer, each component is defined by an XML file, an associated set of JavaScript files, images, and sometimes Eclipse extension points.
+Each component defines its related properties, property types, events, rendering, source generation, RSS mapping, editor icon and description. A component also defines its behavior for a specific part of the target program. Each component is typically a single control (e.g. CEikEdwin) or container (e.g. CAknView or CCoeControl), but are sometimes defined for portions of such controls when it is more convenient for implementation, for example individual items of CAknListBox. Components may also refer to instances of C++ classes (like active objects) or transient dialogs (like progress dialogs).
+Components may derive from other components, allowing them to share, override, and augment key parts of another's implementation. However, only single inheritance is supported.
+A component is defined by a unique ID (qualifiedName), which identifies it to other parts of the UI Designer. These are usually dotted names, for example, "com.nokia.sdt.series60.CAknForm". Components in the UI Designer are marked by an SDK vendor and version. Multiple components with the same unique ID may be defined, if each has a different SDK range. One or none will be selected for use in a design based on the baseline SDK selected, allowing the UI Designer to generate source and resources that are compatible with all SDKs in a project. Sometimes, generated source may compensate for SDK differences with #ifdefs, but this is exceedingly rare in practice.
+Component definitions also include their own version, which means changes in component structure may be detected and acted upon by an update mechanism in Carbide.c++. It's important to design components strictly in accordance with the API versions they target. You want to be sure users will have compilable source no matter what SDK or combination of SDK's they select, even if they change build configurations for their project. Note that this means a component will not necessarily be available for all SDKs in use. The UI Designer can deal gracefully with components that are no longer available for a given SDK, but ample warnings are provided to prevent a design from being saved with a missing component.
+The data model represents a design, wherein instances of components (component instances) are stored, along with their associated property settings and event bindings. The model as a whole also contains a shared language string table and source generation metadata. This design is generated into .uidesign files. The .uidesign files can be graphically displayed in the UI Designer editor or textually displayed in a text editor to reveal their generated XML structure.
+The data model remembers the baseline SDK and component versions used for the last save, so it can detect when components are updated or when the related project's build configurations become incompatible with a design. This will prompt the user to take action.
+The baseline SDK associated with a data model is used in conjunction with the component system to form a component set. The set is a collection of components which are valid for that configuration. The newest compatible component is selected for use in a design.
+A UI design only references components by ID. This allows the structure of components to change without the UI design becoming invalid. Aside from the ID, only the names of properties and events are reflected in the design. Even types of properties are ignored and property values are stored as strings. Thus, a component may add or drop properties between versions, or add or drop events, or (within reason) change the types of properties, without rendering the UI design invalid. The data model will retain any properties that were set, even if they disappear from a component, usually allowing for a design to be converted to a newer or older component version without losing information.
+Components may publish a dynamic set of properties based on runtime checks, allowing them to adapt to the requirements of other component instances. The S60 List Box, for example, uses the "style" property to control which properties are available on its child List Item component instances. Since the data model is flexible and retains properties that no longer exist, fields which relate to other styles may be swapped out without losing information. Thus, you can switch a list box from a "double large" style to a "double time" style to a "single text" style and back without losing any list item information.
+When designing a component, it is important to consider how its data will be used and stored in the data model. Design for flexibility, constructing properties that are independent of each other (as much as possible) and which correspond to specific RSS member fields or C++ setter methods; so they may evolve in coordination with the APIs they are targeting. Also split components into pieces when they have a variable number of contained similar items, rather than making complex array properties.
+A data model specifies a display model, which consists of various aspects on how the design is displayed on screen. It controls how the model is converted into a layout for use by the editor and how that layout is rendered into images. For S60, each component provides a bitmap with transparency and these are drawn on top of each other to make the composite screen.
+A component also provides the applicable layout configurations (screen sizes and portrait/landscape orientations), which supply "look and feel" interfaces that abstract layout-dependent colors, points, rectangles, images, flags, and strings into named keys for use by components. This allows components to be written for any current or future layout. New components will need to implement the rendering interface "IVisualAppearance" to draw their contents onto a transparent bitmap, using SWT GC operations. Alternately, initial implementations can provide a static bitmap image to represent the component.
+The editor provides the user interaction with the data model and display model. It coordinates the editor document, palette, properties view, outline view, and events view. The editor's document represents the layout object tree, while the outline view represents the data model. The properties and events views show information for the currently selected item.
+In the editor, the palette shows a filtered view of components available for the UI design. The containers in the model are queried for compatibility with each component (by the IQueryContainment interface) and only valid combinations are shown in the palette. This is not the full set of installed components. Thus, an important first step for developing new components is to understand how containment works and toggle the "Palette filtering" button in the toolbar so your components show up.
Components are defined within component libraries. The UI Designer supports two types of component libraries:
-The components shipped with the UI Designer are in an Eclipse plugin project. The designer uses the extension point com.nokia.sdt.component.symbian.componentLibrary to locate plugins containing Symbian components. The com.nokia.sdt.series60.componentlibrary plugin implements this extension point. New plugins can be created in the same manner to expose new components.
-Another approach is to use a custom component project. This is an Eclipse project containing one or more components. A key advantage to this approach is that components can easily be developed within your current workspace. Note that custom component projects are not Carbide.c++ projects. They are either simple Eclipse projects or Java projects. These projects do not use the Carbide.c++ build system.
-The files pertaining to components are:
-Components are defined within component libraries. The UI Designer supports two types of component libraries:
+The components shipped with the UI Designer are in an Eclipse plugin project. The designer uses the extension point com.nokia.sdt.component.symbian.componentLibrary to locate plugins containing Symbian components. The com.nokia.sdt.series60.componentlibrary plugin implements this extension point. New plugins can be created in the same manner to expose new components.
+Another approach is to use a custom component project. This is an Eclipse project containing one or more components. A key advantage to this approach is that components can easily be developed within your current workspace. Note that custom component projects are not Carbide.c++ projects. They are either simple Eclipse projects or Java projects. These projects do not use the Carbide.c++ build system.
+The files pertaining to components are:
+The following section provides information on creating your own custom components that appear in the UI Designer and can be used when creating a UI design for your application. First some background information is provided about the basic design of components and how they interact with the UI Designer.
-A UI designer project contains a set of .uidesign files. There is one for each design "view", for example the top-level visual container. There is also a .uidesign file (application.uidesign) for the application as a whole, which includes the AppUi.
-A .uidesign file represents a data model and contains the configuration of a single container or form. The contents of each data model are the persistent state of a set of component instances. Each component instance can have properties, event bindings, and localized strings. Component instances come from the set of available components for a project; based on the selected SDK. Components are listed in the Palette of the UI Designer. Additional component instances are added as the user edits a UI design. Custom components created by a user will also appear in the UI Designer Palette.
-Much of the functionality of the UI Designer is built on components, including determining compatibility across containers, rendering the simulated UI appearance, and generating source code. At the very least, components can be defined by property values, a source code template, and containment rules. Code may also be provided, either in JavaScript or Java, to implement user-defined behavior. However, more complex designs can be implemented into the creation of components.
-The following section provides information on creating your own custom components that appear in the UI Designer and can be used when creating a UI design for your application. First some background information is provided about the basic design of components and how they interact with the UI Designer.
+A UI designer project contains a set of .uidesign files. There is one for each design "view", for example the top-level visual container. There is also a .uidesign file (application.uidesign) for the application as a whole, which includes the AppUi.
+A .uidesign file represents a data model and contains the configuration of a single container or form. The contents of each data model are the persistent state of a set of component instances. Each component instance can have properties, event bindings, and localized strings. Component instances come from the set of available components for a project; based on the selected SDK. Components are listed in the Palette of the UI Designer. Additional component instances are added as the user edits a UI design. Custom components created by a user will also appear in the UI Designer Palette.
+Much of the functionality of the UI Designer is built on components, including determining compatibility across containers, rendering the simulated UI appearance, and generating source code. At the very least, components can be defined by property values, a source code template, and containment rules. Code may also be provided, either in JavaScript or Java, to implement user-defined behavior. However, more complex designs can be implemented into the creation of components.
+This section provides information on how to create your own custom components. Tutorials are provided; along with an explanation of how they were created. More detailed information for the related XML elements used in building a component definition file is also provided.
-Related Custom Component reference information and XML schema details are also available:
- -A component menu is provided to support standard and custom components. If not visible in the main menu bar, you can enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
-Major topics include:
- - - - - + + + + + +This section provides information on how to create your own custom components. Tutorials are provided; along with an explanation of how they were created. More detailed information for the related XML elements used in building a component definition file is also provided.
+Related Custom Component reference information and XML schema details are also available:
+ +A component menu is provided to support standard and custom components. If not visible in the main menu bar, you can enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
+Major topics include:
+ + + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/menu_configure_sourcegen.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/menu_configure_sourcegen.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/menu_configure_sourcegen.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,20 +1,20 @@ - - - - - -Use the Configure SourceGen Debugging… menu item to select components and specify an output directory to place a debug script generated by the UI Designer. A script is generated for the selected components' sourceGen elements in addition to any elements with the debug="true" attribute.
-Use the Configure SourceGen Debugging… menu item to select components and specify an output directory to place a debug script generated by the UI Designer. A script is generated for the selected components' sourceGen elements in addition to any elements with the debug="true" attribute.
+Use the Select Custom Component Projects… menu item to specify one or more projects that UI Designer searches to locate custom components.
-Use the Select Custom Component Projects… menu item to specify one or more projects that UI Designer searches to locate custom components.
+Use the Force Save menu item to save the active UI designer document. If the active document is not from the UI designer then this command saves all open UI designer documents. This is helpful for testing source code generation, allowing you to repeatedly save without making changes to the document.
-Use the Force Save menu item to save the active UI designer document. If the active document is not from the UI designer then this command saves all open UI designer documents. This is helpful for testing source code generation, allowing you to repeatedly save without making changes to the document.
+A component menu is provided to support standard and custom components. If not visible in the main menu bar, you can enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
-A component menu is provided to support standard and custom components. If not visible in the main menu bar, you can enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
+Use the Refresh Components menu item to reload all components from all libraries. This option allows you to make changes to any of your component and script files without having to restart the IDE. JavaScript code is also refreshed, just be sure to save the JavaScript files before refreshing.
-Use the Refresh Components menu item to reload all components from all libraries. This option allows you to make changes to any of your component and script files without having to restart the IDE. JavaScript code is also refreshed, just be sure to save the JavaScript files before refreshing.
+This tutorial explains how to create a top-level container component based on CCoeControl that consists of a simple layout behavior and shows up in the design wizard. The example files for the Equal Container tutorial are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the EqualContainer example files while reading this tutorial.
-Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
-In CCoeControl, children are added at absolute positions and given absolute sizes. These values make it into the generated source. This does not work well for multiple resolutions or portrait vs. landscape modes. So you can create a custom container (EqualContainer) that dynamically calculates the coordinates and sizes for components (children) and places them at equal sizes within the container.
-The goal of this tutorial focuses on the following steps:
-
This tutorial explains how to create a top-level container component based on CCoeControl that consists of a simple layout behavior and shows up in the design wizard. The example files for the Equal Container tutorial are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the EqualContainer example files while reading this tutorial.
+Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
+In CCoeControl, children are added at absolute positions and given absolute sizes. These values make it into the generated source. This does not work well for multiple resolutions or portrait vs. landscape modes. So you can create a custom container (EqualContainer) that dynamically calculates the coordinates and sizes for components (children) and places them at equal sizes within the container.
+The goal of this tutorial focuses on the following steps:
+This tutorial explains how to take an example custom component called VerticalLabel and use it in an S60 UI Designer project. The Vertical Label is an example of a custom S60 visual control component. It is similar to the standard Label component, but draws the label text vertically. The tutorial consists of two versions of the Vertical Label component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 adds JavaScript to render the component when used within a design in the UI Designer.
-Information is provided that explains how to add the component to the UI Designer Palette followed by an examination of how the component was created. This tutorial explains what is relevant to the example. Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
- The example files for the Vertical Label tutorials are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the example files while reading this tutorial.
The goal of this tutorial focuses on the following steps:
-
This tutorial explains how to take an example custom component called VerticalLabel and use it in an S60 UI Designer project. The Vertical Label is an example of a custom S60 visual control component. It is similar to the standard Label component, but draws the label text vertically. The tutorial consists of two versions of the Vertical Label component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 adds JavaScript to render the component when used within a design in the UI Designer.
+Information is provided that explains how to add the component to the UI Designer Palette followed by an examination of how the component was created. This tutorial explains what is relevant to the example. Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
+ The example files for the Vertical Label tutorials are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the example files while reading this tutorial.
The goal of this tutorial focuses on the following steps:
+First create a General Project:
-The project will appear in the Project Explorer view. Select the project and right-click to display the context menu. Select Show in Explorer from the list of menu options. Grab the example zip file from {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer, and unzip the Vertical Label example files into your new simple project folder. The files include:
-The difference between the VerticalLabel1 and VerticalLabel2 example is that the VerticalLabel2 example uses the implementations element to implement the IVisualAppearance class and call a JavaScript file to render the vertical label component and make it visible within the UI Designer. Code within the JavaScript file sets the background, font, size, draws the rectangle, and defines other related properties.
-
First create a General Project:
+The project will appear in the Project Explorer view. Select the project and right-click to display the context menu. Select Show in Explorer from the list of menu options. Grab the example zip file from {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer, and unzip the Vertical Label example files into your new simple project folder. The files include:
+The difference between the VerticalLabel1 and VerticalLabel2 example is that the VerticalLabel2 example uses the implementations element to implement the IVisualAppearance class and call a JavaScript file to render the vertical label component and make it visible within the UI Designer. Code within the JavaScript file sets the background, font, size, draws the rectangle, and defines other related properties.
+If not visible in the main menu bar, enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
-
Figure 1. Components Menu
--
| Force Save | -Forces a save on one or more open design editors. | -
| Refresh Components | -Reloads all components and refreshes open editors. | -
| Select Custom Component Projects... | -Selects which projects are searched for custom components. | -
| Configure SourceGen Debugging... | -Controls dumping of generated JavaScript for source generation. UI Designer will write the generated script for the selected components' <sourceGen> elements to disk, in addition to any elements with the debug="true" attribute. | -
Add Custom Component to UI Designer
-
If not visible in the main menu bar, enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
+
Figure 1. Components Menu
++
| Force Save | +Forces a save on one or more open design editors. | +
| Refresh Components | +Reloads all components and refreshes open editors. | +
| Select Custom Component Projects... | +Selects which projects are searched for custom components. | +
| Configure SourceGen Debugging... | +Controls dumping of generated JavaScript for source generation. UI Designer will write the generated script for the selected components' <sourceGen> elements to disk, in addition to any elements with the debug="true" attribute. | +
Add Custom Component to UI Designer
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_03.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_03.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_03.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,19 +1,19 @@ - - - - - -To add a custom component to the UI Designer, select Components > Select Custom Component Projects... and check custom component projects. UI Designer will search selected projects for custom components. The components will appear in the UI Designer palette for projects that include UI Designer.
-
Figure 1. UI Designer Component Palette
-Create UI Designer Project to Test Custom Component
-
To add a custom component to the UI Designer, select Components > Select Custom Component Projects... and check custom component projects. UI Designer will search selected projects for custom components. The components will appear in the UI Designer palette for projects that include UI Designer.
+
Figure 1. UI Designer Component Palette
+Create UI Designer Project to Test Custom Component
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_04.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_04.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_04.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,34 +1,34 @@ - - - - - -Create a S60 UI Designer project to test the VerticalLabel component. For example, select File > New > Symbian OS C++ Project and choose the "3rd Ed. GUI Application with UI Designer" template. Complete the wizard by filling in required fields and selecting appropriate options on each page of the project creation wizard. On the S60 UI Design Selection page, select the Empty design. On the following page, select Basic Container (CCoeControl) as the Container type.
-Complete the next two pages of the wizard (Basic Settings and Project Directories) or click Finish now to accept the default settings. The project will appear in the Project Explorer view. The graphical representation of the empty UI design container (.uidesign file) will appear in the Carbide.c++ UI Design editor.
-Select either the Vertical Label 1 or Vertical Label 2 component in the palette's Controls group. Then click inside the empty UI design to place the new component inside the design.
-
Figure 1. Custom Component Placed in UI Design
-NOTE The example_verticallabel.rh file must be made accessible to the UI Designer as a system include.
-One way would be to copy the file into an existing "System includes" directory, such as the UIQ SDK's epoc32\include directory. Alternately, you could copy the file into a "User includes" directory in your project (for example, inc) and add the directory as a system included directory in the MMP file.
-To add a directory, double-click on the .mmp file in your project (in group folder by default) to open the MMP editor. Click the Options tab and select the System includes folder in the Compiler Settings group. Click Add to browse to and add the directory containing your .rh file. You can also click the "Add a system include path" link in the Overview page.
-NOTE In your source files the <> brackets denote a system include path, where quotes (" ") indicate a user include.
-
Figure 2 - Compiler Settings Group in MMP Editor
-After placing the custom component into the UI design and saving the file, the example VerticalLabel.cpp file will be placed into the source folder (default is src) of your S60 UI Designer project. The VerticalLabel.cpp file is used to draw the VerticalLabel component on your handheld device or in the emulator at runtime. For the VerticalLabel2 example, the associated JavaScript file is used to draw the custom component only at design time in the UI design.
-Therefore, if you design a visual component and wish to display your custom component in the UI Designer, then you must supply a JavaScript file that implements some predefined interfaces.
-You can save all files and build and run your S60 UI Designer project in the emulator to view the component as part of the application.
-NOTE Ensure that VerticalLabel.cpp is included (checked) in the sources to be compiled. Open your S60 project's .mmp file (located in the group folder) in the Carbide.c++ MMP Editor and select the Sources tab.
-
Figure 2. Include Custom Component .cpp file in MMP Editor
-Remember to refresh your project (F5), refresh components (Components > Refresh Components), clean your project, or perform a Components > Force Save; as needed.
-Vertical Label Component XML Details
-
Create a S60 UI Designer project to test the VerticalLabel component. For example, select File > New > Symbian OS C++ Project and choose the "3rd Ed. GUI Application with UI Designer" template. Complete the wizard by filling in required fields and selecting appropriate options on each page of the project creation wizard. On the S60 UI Design Selection page, select the Empty design. On the following page, select Basic Container (CCoeControl) as the Container type.
+Complete the next two pages of the wizard (Basic Settings and Project Directories) or click Finish now to accept the default settings. The project will appear in the Project Explorer view. The graphical representation of the empty UI design container (.uidesign file) will appear in the Carbide.c++ UI Design editor.
+Select either the Vertical Label 1 or Vertical Label 2 component in the palette's Controls group. Then click inside the empty UI design to place the new component inside the design.
+
Figure 1. Custom Component Placed in UI Design
+NOTE The example_verticallabel.rh file must be made accessible to the UI Designer as a system include.
+One way would be to copy the file into an existing "System includes" directory, such as the UIQ SDK's epoc32\include directory. Alternately, you could copy the file into a "User includes" directory in your project (for example, inc) and add the directory as a system included directory in the MMP file.
+To add a directory, double-click on the .mmp file in your project (in group folder by default) to open the MMP editor. Click the Options tab and select the System includes folder in the Compiler Settings group. Click Add to browse to and add the directory containing your .rh file. You can also click the "Add a system include path" link in the Overview page.
+NOTE In your source files the <> brackets denote a system include path, where quotes (" ") indicate a user include.
+
Figure 2 - Compiler Settings Group in MMP Editor
+After placing the custom component into the UI design and saving the file, the example VerticalLabel.cpp file will be placed into the source folder (default is src) of your S60 UI Designer project. The VerticalLabel.cpp file is used to draw the VerticalLabel component on your handheld device or in the emulator at runtime. For the VerticalLabel2 example, the associated JavaScript file is used to draw the custom component only at design time in the UI design.
+Therefore, if you design a visual component and wish to display your custom component in the UI Designer, then you must supply a JavaScript file that implements some predefined interfaces.
+You can save all files and build and run your S60 UI Designer project in the emulator to view the component as part of the application.
+NOTE Ensure that VerticalLabel.cpp is included (checked) in the sources to be compiled. Open your S60 project's .mmp file (located in the group folder) in the Carbide.c++ MMP Editor and select the Sources tab.
+
Figure 2. Include Custom Component .cpp file in MMP Editor
+Remember to refresh your project (F5), refresh components (Components > Refresh Components), clean your project, or perform a Components > Force Save; as needed.
+Vertical Label Component XML Details
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_05.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_05.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_s60/verticallabel_tutorial_05.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,154 +1,154 @@ - - - - - -The tutorial consists of two versions of the VerticalLabel component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 uses JavaScript to display the component in the UI Designer when designing your user interface.
-The following information explains what is relevant to the tutorial. Refer to the XML component schema documentation for all the details. -The root element for defining a custom component begins with the <componentDefinition> element as shown in the VerticalLabel1.component and VerticalLabel2.component files. It contains the necessary name space attributes, making the component schema namespace the default.
-The component element defines the majority of the component properties, attributes, source mapping and souce generation declarations. The following snippet is from the example .component files:
-<component friendlyName="%friendlyName" - qualifiedName="com.example.VerticalLabel1" - baseComponent="com.nokia.sdt.series60.CCoeControlBase" - category="Controls" version="1.0" - instanceNameRoot="vlabel"> - <symbian - sdkName="com.nokia.series60" minSDKVersion="2.0" - className="CVerticalLabel"/>-
Strings prefixed with % are localized strings that are automatically looked up in the accompanying properties files, such as VerticalLabel1.properties.
-Note that this component derives from CCoeControlBase, which is a component included with Carbide.c++. It provides much of the default behavior, including needed source code generation.
-The <symbian> element specifies that this component is compatible with all SDKs from 2.0 forward and the class name in the VerticalLabel.cpp file used to draw the component at run time is CVerticalLabel.
-<symbian sdkName="com.nokia.series60" minSDKVersion="2.0" className="CVerticalLabel"/>-
The sdkName property identifies the Symbian OS variant with which the component is compatible. Currently the only recognized SDK name for S60 is "com.nokia.series60".
-TIP Enter devices at a command prompt (C:\>devices) to display a list of installed and properly configured SDKs.
-In the VerticalLabel1 example, the <designerImages> element uses one image. This is the static layout image visible in the UI design. This is used in place of writing rendering script in a JavaScript file. You will only see a static graphic in the UI designer. Since icon images have also been omitted, a default image is displayed in the palette and no image is visible in the outline view. For example:
-<designerImages layoutImageFile="layoutImage.png"/>-
In the VerticalLabel2 example, the <designerImages> element uses custom icon images (.png files) to represent the component in the palette and outline views. The static layout image file can be removed since JavaScript rendering code has been added to display the component in the UI design. For example:
-<designerImages smallIconFile="VerticalLabel_sm.png" - largeIconFile="VerticalLabel.png"/>-
Images are validated and rendered on a per-component basis. Each component may have different restrictions or guidelines for the type or size of images that appear. Images appearing in forms and lists will be automatically scaled by the platform. This requires a reference to another interface the component system understands (IImagePropertyRenderingInfo); and can be declared as shown in the following code fragment.
-<implementations> - <implementation> - <interface id="com.nokia.sdt.datamodel.adapter.IImagePropertyRenderingInfo"/> - <script file="MyComponent.js" prototype="MyComponent"/> - </implementation> -</implementations>-
The Attributes element allows you to declare miscellaneous characteristics about your component. For example, the following snippet is from the example Vertical Label .component files.
-<attributes> - <attribute key="cpp-class-name">CVerticalLabel</attribute> - <attribute key="is-ccoecontrol-content">true</attribute> -</attributes>-
The cpp-class-name attribute is used by the source generation element (<sourceGen>) that is inherited from CCoeControlBase. This allows you to specify the name of the C++ class to use in the generated source. The is-ccoecontrol-content attribute specifies that this component is compatible with the CCoeControl container. This attribute is understood by the S60 CCoeControl container component because of the specifics of how its containment query script is implemented.
-NOTE This attribute has to be defined as "true" for the component to be placed in the UI Designer palette.
-Properties are the data values you can define for a component instance. The text property is the default text drawn by the vertical label component. Note that it is a localized string, so you may provide different values for each language added to the application. The lineWidth property determines the thickness of the border rectangle drawn around the component. A value of zero (0) indicates no border will be drawn. Note that default, minimum, and maximum values are specified. The default attribute is optional and provides an initial value. The optional minimum and maximum attributes provide range checking for integer properties.
-<properties> - <property name="text" type="localizedString" default="label"/> - <property name="lineWidth" type="integer" default="1" minValue="0" maxValue="5"/> -</properties>-
The <implementations> element is used in the VerticalLabel2.component example in order to render the component in the UI design. The <implementations> element informs the UI designer that the custom component has code. Implementations can be provided in either JavaScript or Java.
-Each implementation declaration has a list of one or more interfaces it fulfills. In this case the IVisualAppearance interface is implemented. This allows us to render an image corresponding to the current property values and provide feedback on the appropriate sizing for the component. The <script> element informs the UI designer which file has the script and the name of the JavaScript prototype object to instantiate, as shown in the following snippet.
-<implementations> - <implementation> - <interface id="com.nokia.sdt.datamodel.adapter.IVisualAppearance"/> - <script file="VerticalLabel.js" prototype="VerticalLabel"/> - </implementation> -</implementations>-
The example JavaScript file (VerticalLabel.js) contains an empty function to instantiate the JavaScript prototype. Note that the JavaScript file needs to be located as a sibling to the component file that references it.
-function VerticalLabel() {
- }
-The following code in the JavaScript file declares the draw method. It takes three parameters:
-VerticalLabel.prototype.draw = function(instance, laf, graphics) {
-The font object is obtained from the look and feel object. Since this is a simple example the font is hard-coded to a standard S60 font.
-var font = laf.getFont("NormalFont");
- graphics.setFont(font);
-The background color needs to be set since anti-aliased text with a transparent background is drawn. In the UI Designer, each component is rendered into a bitmap with 'transparent pixel' support. The bitmap does not have an alpha channel. Thus, if the background color is not set, the 'transparent pixel' would be blended with the antialiased text, resulting in an orange border.
-graphics.setBackground(laf.getColor("EEikColorControlBackground"));
-Next a rectangular border and the text within the border is drawn. The bounds and position of the text are calculated accordingly.
-var properties = instance.properties; - var lineWidth = properties.lineWidth; - var halfLineWidth = lineWidth/2; - var textBounds = new Rectangle(halfLineWidth, halfLineWidth, - properties.size.width - halfLineWidth, - properties.size.height - halfLineWidth); - var x = lineWidth + 1; - var y = properties.size.height - lineWidth - 1;-
The rotated text is then drawn.
-graphics.drawRotatedString(properties.text, textBounds, x, y, -1.57, true);-
If requested, the border is drawn.
-if (lineWidth > 0) {
- graphics.setLineWidth(lineWidth);
- x = y = halfLineWidth;
-
- graphics.drawRectangle(x, y,
- properties.size.width-lineWidth,
- properties.size.height-lineWidth);
- }
-The getPreferredSize method is called to calculate the initial size of the component instance. The wHint and hHint parameters will be greater than zero when the user has dragged out a rectangle to specify the initial component size. That should be respected, unless that size is inappropriate for your component. The example script respects the requested size and specifies defaults, if necessary.
-VerticalLabel.prototype.getPreferredSize = function(instance, laf, wHint, hHint) {
- var width = wHint > 0? wHint : 20;
- var height = hHint > 0? hHint : 100;
- return new Point(width, height);
- }
-The Vertical Label component uses an RSS include file (example_verticallabel.rh). This file defines a custom resource used to initialize the component. Since our component uses a localized string it is especially important to use a resource. The <sourceMapping> element contains information on how to convert from property values to RSS statements, and from RSS statements back to property values.
-The <mapResource> element tells the RSS generator to create a resource of type EXAMPLE_VERTICAL_LABEL, and that the example_verticallabel.rh file is needed to create compilable source code. The RSS generator has flexible support for mapping properties to resources. Only simple conversions are needed, which can be done with the <mapSimpleMember> element. This has attributes that indicate a given property should be used to initialize a specific resource member. Refer to the "source mapping" XML schema documentation for details on all available mappings. Detailed documentation on the schema can be found in the plugins folder of your Carbide.c++ installation, for example, the default location at C:\Program Files\Nokia\Carbide.c++ v1.3\plugins\com.nokia.sdt.component.symbian_1.3.0.3. Also examine the S60 components included with the UI designer for lots of examples; located at <Carbide installation path>/plugins/com.nokia.sdt.series60.componentlibrary/components.
-<sourceMapping> - <mapResource struct="EXAMPLE_VERTICAL_LABEL" headers="example_verticallabel.rh"> - <mapSimpleMember property="text" member="txt"/> - <mapSimpleMember property="lineWidth" member="line_size"/> - </mapResource> -</sourceMapping>-
The <sourceGen> element contains all the information needed to generate C++ code. Because this example is deriving from CCoeControlBase and generating code for an existing container (CCoeControl), there is a lot of existing infrastructure to leverage. Source code generation is performed by executing JavaScript scripts. There is a layer above raw JavaScript that creates scripts by way of template expansion, like with PHP, JPS, ASP, etc. With templates you can define variables, or escape out to arbitrary script code. The following code snippet is from the Vertical Label .component files.
-<sourceGen forms="Container">-
- <useTemplateGroup ids="CLASS_CONTRIBS" /> - <useTemplate ids="INIT_FROM_CONTAINER" /> - <useTemplateGroup ids="CONTAINER_CHILD_CONTRIBS" /> - <useTemplate ids="LAYOUT_CONTROLS" /> - <inline> - if (Engine.formMatches(form, [""])) { - // create files if missing - Engine.createFromStockFile("inc", "VerticalLabel.h", "VerticalLabel.h"); - Engine.createFromStockFile("src", "VerticalLabel.cpp", "VerticalLabel.cpp"); - } - this.getCppSystemIncludes(contribs, ["barsread.h", "stringloader.h", "eikenv.h"]); - </inline> - <useTemplateGroup ids="GenerateCommonControlEvents GenerateStateChangedEvent"/> - <useTemplateGroup ids="GenerateRequestingFocusEvent GenerateRequestingExitEvent"/> - <useTemplateGroup ids="GenerateRequestingCancelEvent GenerateInteractionRefusedEvent"/> - <useTemplateGroup ids="GeneratePrepareFocusTransitionEvent"/> -
- <template location="MAIN_USER_INCLUDES"><![CDATA[#include "VerticalLabel.h"]]> - </template> -</sourceGen>
Since source code generation is very detailed and specific, deriving from a component does not automatically enable source code generation. The derived component must specify what to generate, either completely or by referencing existing templates. Templates defined in CCoeControlBase can be reused.
-A template group is a set of templates referenced by a single name. The CLASS_CONTRIBS group is the common boilerplate for defining a member variable in the class; initializing the member and deallocating the member.
-The INIT_FROM_CONTAINER template emits the standard Symbian code for allocating the component within a CCoeControl container. This includes allocating the object, reading the state from a resource, and managing the cleanup stack.
-The LAYOUT_CONTROLS template generates source to size and position the component according to the properties set in the UI designer.
-The <inline> element inserts JavaScript code. This example calls a predefined function to emit the header files needed to use this component.
-The additional <useTemplateGroup> elements (after the inline element) references existing templates in order to support events. Since the VerticalLabel example is a subclass of CCoeControl you want to support all the events in a CCoeControl container. Since the example inherits from CCoeControlBase, the appropriate event declarations and templates have already been inherited.
-The final <template> element in this snippet is used to define a new template in order to insert the #include "VerticalLabel.h" statement for the class header file.
-
The tutorial consists of two versions of the VerticalLabel component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 uses JavaScript to display the component in the UI Designer when designing your user interface.
+The following information explains what is relevant to the tutorial. Refer to the XML component schema documentation for all the details. +The root element for defining a custom component begins with the <componentDefinition> element as shown in the VerticalLabel1.component and VerticalLabel2.component files. It contains the necessary name space attributes, making the component schema namespace the default.
+The component element defines the majority of the component properties, attributes, source mapping and souce generation declarations. The following snippet is from the example .component files:
+<component friendlyName="%friendlyName" + qualifiedName="com.example.VerticalLabel1" + baseComponent="com.nokia.sdt.series60.CCoeControlBase" + category="Controls" version="1.0" + instanceNameRoot="vlabel"> + <symbian + sdkName="com.nokia.series60" minSDKVersion="2.0" + className="CVerticalLabel"/>+
Strings prefixed with % are localized strings that are automatically looked up in the accompanying properties files, such as VerticalLabel1.properties.
+Note that this component derives from CCoeControlBase, which is a component included with Carbide.c++. It provides much of the default behavior, including needed source code generation.
+The <symbian> element specifies that this component is compatible with all SDKs from 2.0 forward and the class name in the VerticalLabel.cpp file used to draw the component at run time is CVerticalLabel.
+<symbian sdkName="com.nokia.series60" minSDKVersion="2.0" className="CVerticalLabel"/>+
The sdkName property identifies the Symbian OS variant with which the component is compatible. Currently the only recognized SDK name for S60 is "com.nokia.series60".
+TIP Enter devices at a command prompt (C:\>devices) to display a list of installed and properly configured SDKs.
+In the VerticalLabel1 example, the <designerImages> element uses one image. This is the static layout image visible in the UI design. This is used in place of writing rendering script in a JavaScript file. You will only see a static graphic in the UI designer. Since icon images have also been omitted, a default image is displayed in the palette and no image is visible in the outline view. For example:
+<designerImages layoutImageFile="layoutImage.png"/>+
In the VerticalLabel2 example, the <designerImages> element uses custom icon images (.png files) to represent the component in the palette and outline views. The static layout image file can be removed since JavaScript rendering code has been added to display the component in the UI design. For example:
+<designerImages smallIconFile="VerticalLabel_sm.png" + largeIconFile="VerticalLabel.png"/>+
Images are validated and rendered on a per-component basis. Each component may have different restrictions or guidelines for the type or size of images that appear. Images appearing in forms and lists will be automatically scaled by the platform. This requires a reference to another interface the component system understands (IImagePropertyRenderingInfo); and can be declared as shown in the following code fragment.
+<implementations> + <implementation> + <interface id="com.nokia.sdt.datamodel.adapter.IImagePropertyRenderingInfo"/> + <script file="MyComponent.js" prototype="MyComponent"/> + </implementation> +</implementations>+
The Attributes element allows you to declare miscellaneous characteristics about your component. For example, the following snippet is from the example Vertical Label .component files.
+<attributes> + <attribute key="cpp-class-name">CVerticalLabel</attribute> + <attribute key="is-ccoecontrol-content">true</attribute> +</attributes>+
The cpp-class-name attribute is used by the source generation element (<sourceGen>) that is inherited from CCoeControlBase. This allows you to specify the name of the C++ class to use in the generated source. The is-ccoecontrol-content attribute specifies that this component is compatible with the CCoeControl container. This attribute is understood by the S60 CCoeControl container component because of the specifics of how its containment query script is implemented.
+NOTE This attribute has to be defined as "true" for the component to be placed in the UI Designer palette.
+Properties are the data values you can define for a component instance. The text property is the default text drawn by the vertical label component. Note that it is a localized string, so you may provide different values for each language added to the application. The lineWidth property determines the thickness of the border rectangle drawn around the component. A value of zero (0) indicates no border will be drawn. Note that default, minimum, and maximum values are specified. The default attribute is optional and provides an initial value. The optional minimum and maximum attributes provide range checking for integer properties.
+<properties> + <property name="text" type="localizedString" default="label"/> + <property name="lineWidth" type="integer" default="1" minValue="0" maxValue="5"/> +</properties>+
The <implementations> element is used in the VerticalLabel2.component example in order to render the component in the UI design. The <implementations> element informs the UI designer that the custom component has code. Implementations can be provided in either JavaScript or Java.
+Each implementation declaration has a list of one or more interfaces it fulfills. In this case the IVisualAppearance interface is implemented. This allows us to render an image corresponding to the current property values and provide feedback on the appropriate sizing for the component. The <script> element informs the UI designer which file has the script and the name of the JavaScript prototype object to instantiate, as shown in the following snippet.
+<implementations> + <implementation> + <interface id="com.nokia.sdt.datamodel.adapter.IVisualAppearance"/> + <script file="VerticalLabel.js" prototype="VerticalLabel"/> + </implementation> +</implementations>+
The example JavaScript file (VerticalLabel.js) contains an empty function to instantiate the JavaScript prototype. Note that the JavaScript file needs to be located as a sibling to the component file that references it.
+function VerticalLabel() {
+ }
+The following code in the JavaScript file declares the draw method. It takes three parameters:
+VerticalLabel.prototype.draw = function(instance, laf, graphics) {
+The font object is obtained from the look and feel object. Since this is a simple example the font is hard-coded to a standard S60 font.
+var font = laf.getFont("NormalFont");
+ graphics.setFont(font);
+The background color needs to be set since anti-aliased text with a transparent background is drawn. In the UI Designer, each component is rendered into a bitmap with 'transparent pixel' support. The bitmap does not have an alpha channel. Thus, if the background color is not set, the 'transparent pixel' would be blended with the antialiased text, resulting in an orange border.
+graphics.setBackground(laf.getColor("EEikColorControlBackground"));
+Next a rectangular border and the text within the border is drawn. The bounds and position of the text are calculated accordingly.
+var properties = instance.properties; + var lineWidth = properties.lineWidth; + var halfLineWidth = lineWidth/2; + var textBounds = new Rectangle(halfLineWidth, halfLineWidth, + properties.size.width - halfLineWidth, + properties.size.height - halfLineWidth); + var x = lineWidth + 1; + var y = properties.size.height - lineWidth - 1;+
The rotated text is then drawn.
+graphics.drawRotatedString(properties.text, textBounds, x, y, -1.57, true);+
If requested, the border is drawn.
+if (lineWidth > 0) {
+ graphics.setLineWidth(lineWidth);
+ x = y = halfLineWidth;
+
+ graphics.drawRectangle(x, y,
+ properties.size.width-lineWidth,
+ properties.size.height-lineWidth);
+ }
+The getPreferredSize method is called to calculate the initial size of the component instance. The wHint and hHint parameters will be greater than zero when the user has dragged out a rectangle to specify the initial component size. That should be respected, unless that size is inappropriate for your component. The example script respects the requested size and specifies defaults, if necessary.
+VerticalLabel.prototype.getPreferredSize = function(instance, laf, wHint, hHint) {
+ var width = wHint > 0? wHint : 20;
+ var height = hHint > 0? hHint : 100;
+ return new Point(width, height);
+ }
+The Vertical Label component uses an RSS include file (example_verticallabel.rh). This file defines a custom resource used to initialize the component. Since our component uses a localized string it is especially important to use a resource. The <sourceMapping> element contains information on how to convert from property values to RSS statements, and from RSS statements back to property values.
+The <mapResource> element tells the RSS generator to create a resource of type EXAMPLE_VERTICAL_LABEL, and that the example_verticallabel.rh file is needed to create compilable source code. The RSS generator has flexible support for mapping properties to resources. Only simple conversions are needed, which can be done with the <mapSimpleMember> element. This has attributes that indicate a given property should be used to initialize a specific resource member. Refer to the "source mapping" XML schema documentation for details on all available mappings. Detailed documentation on the schema can be found in the plugins folder of your Carbide.c++ installation, for example, the default location at C:\Program Files\Nokia\Carbide.c++ v1.3\plugins\com.nokia.sdt.component.symbian_1.3.0.3. Also examine the S60 components included with the UI designer for lots of examples; located at <Carbide installation path>/plugins/com.nokia.sdt.series60.componentlibrary/components.
+<sourceMapping> + <mapResource struct="EXAMPLE_VERTICAL_LABEL" headers="example_verticallabel.rh"> + <mapSimpleMember property="text" member="txt"/> + <mapSimpleMember property="lineWidth" member="line_size"/> + </mapResource> +</sourceMapping>+
The <sourceGen> element contains all the information needed to generate C++ code. Because this example is deriving from CCoeControlBase and generating code for an existing container (CCoeControl), there is a lot of existing infrastructure to leverage. Source code generation is performed by executing JavaScript scripts. There is a layer above raw JavaScript that creates scripts by way of template expansion, like with PHP, JPS, ASP, etc. With templates you can define variables, or escape out to arbitrary script code. The following code snippet is from the Vertical Label .component files.
+<sourceGen forms="Container">+
+ <useTemplateGroup ids="CLASS_CONTRIBS" /> + <useTemplate ids="INIT_FROM_CONTAINER" /> + <useTemplateGroup ids="CONTAINER_CHILD_CONTRIBS" /> + <useTemplate ids="LAYOUT_CONTROLS" /> + <inline> + if (Engine.formMatches(form, [""])) { + // create files if missing + Engine.createFromStockFile("inc", "VerticalLabel.h", "VerticalLabel.h"); + Engine.createFromStockFile("src", "VerticalLabel.cpp", "VerticalLabel.cpp"); + } + this.getCppSystemIncludes(contribs, ["barsread.h", "stringloader.h", "eikenv.h"]); + </inline> + <useTemplateGroup ids="GenerateCommonControlEvents GenerateStateChangedEvent"/> + <useTemplateGroup ids="GenerateRequestingFocusEvent GenerateRequestingExitEvent"/> + <useTemplateGroup ids="GenerateRequestingCancelEvent GenerateInteractionRefusedEvent"/> + <useTemplateGroup ids="GeneratePrepareFocusTransitionEvent"/> +
+ <template location="MAIN_USER_INCLUDES"><![CDATA[#include "VerticalLabel.h"]]> + </template> +</sourceGen>
Since source code generation is very detailed and specific, deriving from a component does not automatically enable source code generation. The derived component must specify what to generate, either completely or by referencing existing templates. Templates defined in CCoeControlBase can be reused.
+A template group is a set of templates referenced by a single name. The CLASS_CONTRIBS group is the common boilerplate for defining a member variable in the class; initializing the member and deallocating the member.
+The INIT_FROM_CONTAINER template emits the standard Symbian code for allocating the component within a CCoeControl container. This includes allocating the object, reading the state from a resource, and managing the cleanup stack.
+The LAYOUT_CONTROLS template generates source to size and position the component according to the properties set in the UI designer.
+The <inline> element inserts JavaScript code. This example calls a predefined function to emit the header files needed to use this component.
+The additional <useTemplateGroup> elements (after the inline element) references existing templates in order to support events. Since the VerticalLabel example is a subclass of CCoeControl you want to support all the events in a CCoeControl container. Since the example inherits from CCoeControlBase, the appropriate event declarations and templates have already been inherited.
+The final <template> element in this snippet is used to define a new template in order to insert the #include "VerticalLabel.h" statement for the class header file.
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,30 +1,30 @@ - - - - - -This tutorial explains how to take an example custom component called VerticalLabel and use it in an UIQ UI Designer project. The Vertical Label is an example of a custom visual control component. It is similar to the standard Label component, but draws the label text vertically. The tutorial consists of two versions of the Vertical Label component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 adds JavaScript to render the component when used within a design in the UI Designer.
-Information is provided that explains how to add the component to the UI Designer Palette followed by an examination of how the component was created. This tutorial explains what is relevant to the example. Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
-The example files for the Vertical Label tutorials are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the example files while reading this tutorial.
-The goal of this tutorial focuses on the following steps:
-
This tutorial explains how to take an example custom component called VerticalLabel and use it in an UIQ UI Designer project. The Vertical Label is an example of a custom visual control component. It is similar to the standard Label component, but draws the label text vertically. The tutorial consists of two versions of the Vertical Label component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 adds JavaScript to render the component when used within a design in the UI Designer.
+Information is provided that explains how to add the component to the UI Designer Palette followed by an examination of how the component was created. This tutorial explains what is relevant to the example. Please refer to the component XML schema documentation for all the XML element details. Detailed documentation on the schema can be found in the reference section under Component XSD Description.
+The example files for the Vertical Label tutorials are provided in a zip file in the s60 components plugin located at: {Carbide_Installation_Dir}\plugins\com.nokia.sdt.series60.componentlibrary_version\templates\tutorials\example_components\example_components.zip, where version is the current version of UI Designer. Refer to the example files while reading this tutorial.
+The goal of this tutorial focuses on the following steps:
+First create a General Project:
-The project will appear in the Project Explorer view. Select the project and right-click to display the context menu. Select Show in Explorer from the list of menu options. Grab the example zip file from {Carbide_Installation_Dir}\plugins\com.nokia.carbide.cpp.uiq.components_1.3.0.x\templates\tutorials\example_components\example_components.zip and unzip the Vertical Label example files into your new simple project folder. The files include:
-The difference between the VerticalLabel1 and VerticalLabel2 example is that the VerticalLabel2 example uses the implementations element to implement the IVisualAppearance class and call a JavaScript file to render the vertical label component and make it visible within the UI Designer. Code within the JavaScript file sets the background, font, size, draws the rectangle, and defines other related properties.
-
First create a General Project:
+The project will appear in the Project Explorer view. Select the project and right-click to display the context menu. Select Show in Explorer from the list of menu options. Grab the example zip file from {Carbide_Installation_Dir}\plugins\com.nokia.carbide.cpp.uiq.components_1.3.0.x\templates\tutorials\example_components\example_components.zip and unzip the Vertical Label example files into your new simple project folder. The files include:
+The difference between the VerticalLabel1 and VerticalLabel2 example is that the VerticalLabel2 example uses the implementations element to implement the IVisualAppearance class and call a JavaScript file to render the vertical label component and make it visible within the UI Designer. Code within the JavaScript file sets the background, font, size, draws the rectangle, and defines other related properties.
+If not visible in the main menu bar, enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
-
Figure 1. Components Menu
--
| Force Save | -Forces a save on one or more open design editors. | -
| Refresh Components | -Reloads all components and refreshes open editors. | -
| Select Custom Component Projects... | -Selects which projects are searched for custom components. | -
| Configure SourceGen Debugging... | -Controls dumping of generated JavaScript for source generation. UI Designer will write the generated script for the selected components' <sourceGen> elements to disk, in addition to any elements with the debug="true" attribute. | -
Add Custom Component to UI Designer
-
If not visible in the main menu bar, enable the Components menu. Select Window > Customize Perspective... and select the Commands tab. In the list of Available command groups, check Carbide.c++ UI Designer Components and click OK to close the dialog box. The Components menu will appear between the Project and Run menus.
+
Figure 1. Components Menu
++
| Force Save | +Forces a save on one or more open design editors. | +
| Refresh Components | +Reloads all components and refreshes open editors. | +
| Select Custom Component Projects... | +Selects which projects are searched for custom components. | +
| Configure SourceGen Debugging... | +Controls dumping of generated JavaScript for source generation. UI Designer will write the generated script for the selected components' <sourceGen> elements to disk, in addition to any elements with the debug="true" attribute. | +
Add Custom Component to UI Designer
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_03.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_03.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_03.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,19 +1,19 @@ - - - - - -To add a custom component to the UI Designer, select Components > Select Custom Component Projects... and check custom component projects. UI Designer will search selected projects for custom components. The components will appear in the UI Designer palette.
-
Figure 1. UI Designer Component Palette
-Create UI Designer Project to Test Custom Component
-
To add a custom component to the UI Designer, select Components > Select Custom Component Projects... and check custom component projects. UI Designer will search selected projects for custom components. The components will appear in the UI Designer palette.
+
Figure 1. UI Designer Component Palette
+Create UI Designer Project to Test Custom Component
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_04.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_04.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_04.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,30 +1,30 @@ - - - - - -Create a UIQ UI Designer project to test the VerticalLabel component. For example, select File > New > Symbian OS C++ Project and choose the "3.x GUI Application with UI Designer" template. Complete the wizard by filling in required fields and selecting appropriate options on each page of the project creation wizard.
-Complete the last two pages of the wizard (Basic Settings and Project Directories) or click Finish at the UIQ UI Design Properties page to accept the default settings. The project will appear in the Project Explorer view. The graphical representation of the selected view (.uidesign file) will appear in the Carbide.c++ UI Design editor.
-Select either the Vertical Label 1 or Vertical Label 2 component in the palette's Custom Controls group. Then click inside the empty UI design to place the new component inside the design.
-
Figure 1. Custom Component Placed in UI Design
-NOTE The example_verticallabel.rh and example_verticallabel.hrh files must be made accessible to the UI Designer as system includes.
-One way would be to copy these files into an existing "System includes" directory, such as the UIQ SDK's epoc32\include directory. Alternately, you could copy them into a "User includes" directory in your project (for example, inc) and add the directory as a system included directory in the MMP file.
-To add a directory, double-click on the .mmp file in your project (in group folder by default) to open the MMP editor. Click the Options tab and select the System includes folder in the Compiler Settings group. Click Add to browse to and add the directory containing your .rh and .hrh files. You can also click the "Add a system include path" link in the Overview page.
-NOTE In your source files the <> brackets denote a system include path, where quotes (" ") indicate a user include.
-
Figure 2 - Compiler Settings Group in MMP Editor
-After placing the custom component into the UI design and saving the file, the example VerticalLabel.cpp file will be placed into the source folder (default is src) of your UI Designer project. The VerticalLabel.cpp file is used to draw the VerticalLabel component on your handheld device or in the emulator at runtime. For the VerticalLabel2 example, the associated JavaScript file is used to draw the custom component only at design time in the UI design. Therefore, if you design a visual component and wish to display your custom component in the UI Designer, then you must supply a JavaScript file that implements some predefined interfaces.
-You can save all files and build and run your UI Designer project in the emulator to view the component as part of the application.
-Remember to refresh your project (F5), refresh components (Components > Refresh Components), clean your project, or perform a Components > Force Save; as needed.
-Vertical Label Component XML Details
-
Create a UIQ UI Designer project to test the VerticalLabel component. For example, select File > New > Symbian OS C++ Project and choose the "3.x GUI Application with UI Designer" template. Complete the wizard by filling in required fields and selecting appropriate options on each page of the project creation wizard.
+Complete the last two pages of the wizard (Basic Settings and Project Directories) or click Finish at the UIQ UI Design Properties page to accept the default settings. The project will appear in the Project Explorer view. The graphical representation of the selected view (.uidesign file) will appear in the Carbide.c++ UI Design editor.
+Select either the Vertical Label 1 or Vertical Label 2 component in the palette's Custom Controls group. Then click inside the empty UI design to place the new component inside the design.
+
Figure 1. Custom Component Placed in UI Design
+NOTE The example_verticallabel.rh and example_verticallabel.hrh files must be made accessible to the UI Designer as system includes.
+One way would be to copy these files into an existing "System includes" directory, such as the UIQ SDK's epoc32\include directory. Alternately, you could copy them into a "User includes" directory in your project (for example, inc) and add the directory as a system included directory in the MMP file.
+To add a directory, double-click on the .mmp file in your project (in group folder by default) to open the MMP editor. Click the Options tab and select the System includes folder in the Compiler Settings group. Click Add to browse to and add the directory containing your .rh and .hrh files. You can also click the "Add a system include path" link in the Overview page.
+NOTE In your source files the <> brackets denote a system include path, where quotes (" ") indicate a user include.
+
Figure 2 - Compiler Settings Group in MMP Editor
+After placing the custom component into the UI design and saving the file, the example VerticalLabel.cpp file will be placed into the source folder (default is src) of your UI Designer project. The VerticalLabel.cpp file is used to draw the VerticalLabel component on your handheld device or in the emulator at runtime. For the VerticalLabel2 example, the associated JavaScript file is used to draw the custom component only at design time in the UI design. Therefore, if you design a visual component and wish to display your custom component in the UI Designer, then you must supply a JavaScript file that implements some predefined interfaces.
+You can save all files and build and run your UI Designer project in the emulator to view the component as part of the application.
+Remember to refresh your project (F5), refresh components (Components > Refresh Components), clean your project, or perform a Components > Force Save; as needed.
+Vertical Label Component XML Details
+ + + + diff -r 6433764204b0 -r b99f029f4d47 carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_05.htm --- a/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_05.htm Thu Jul 29 13:03:15 2010 -0500 +++ b/carbidesdk/com.nokia.carbide.cpp.sdk.doc.user/html/CustomComponents/tutorials/verticallabel_uiq/verticallabel_tutorial_05.htm Thu Jul 29 14:08:00 2010 -0500 @@ -1,199 +1,199 @@ - - - - - -The tutorial consists of two versions of the VerticalLabel component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 uses JavaScript to display the component in the UI Designer when designing your user interface.
-The following information explains what is relevant to the tutorial. Refer to the XML component schema documentation for all the details. -The root element for defining a custom component begins with the <componentDefinition> element as shown in the VerticalLabel1.component and VerticalLabel2.component files. It contains the necessary name space attributes, making the component schema namespace the default.
-The component element defines the majority of the component properties, attributes, source mapping and souce generation declarations. The following snippet is from the example .component files:
-<component friendlyName="%friendlyName" - qualifiedName="com.example.uiq.VerticalLabel1" - baseComponent="com.nokia.carbide.uiq.ControlCollectionItemBase" - category="Custom Controls" version="1.0" - instanceNameRoot="vlabel"> - <symbian - sdkName="com.uiq" minSDKVersion="3.0" - className="CVerticalLabel"/>-
Strings prefixed with % are localized strings that are automatically looked up in the accompanying properties files, such as VerticalLabel1.properties.
-Note that this component derives from ControlCollectionItemBase, which is a component included with Carbide.c++. It provides some of the source code generation, as well as allowing it to behave like the other UIQ controls in the UI designer in that they are used in a design's different layout configurations as references in the control collection.
-The <symbian> element specifies that this component is compatible with all SDKs from 3.0 forward and the class name in the VerticalLabel.cpp file used to draw the component at run time is CVerticalLabel.
-<symbian sdkName="com.uiq" minSDKVersion="3.0" className="CVerticalLabel"/>-
The sdkName property identifies the Symbian OS variant with which the component is compatible. Currently the only recognized SDK name for UIQ is "com.uiq".
-TIP Enter devices at a command prompt (C:\>devices) to display a list of installed and properly configured SDKs.
-In the VerticalLabel1 example, the <designerImages> element uses one image. This is the static layout image visible in the UI design. This is used in place of writing rendering script in a JavaScript file. You will only see a static graphic in the UI designer and its sizing by the current layout manager will not be defined by the component. Since icon images have also been omitted, default images are displayed in the palette and in the outline view. For example:
-<designerImages layoutImageFile="layoutImage.png"/>-
In the VerticalLabel2 example, the <designerImages> element uses custom icon images (.png files) to represent the component in the palette and outline views. The static layout image file can be removed since JavaScript rendering code has been added to display the component in the UI design. For example:
-<designerImages smallIconFile="VerticalLabel_sm.png" - largeIconFile="VerticalLabel.png"/>-
Images are validated and rendered on a per-component basis. Each component may have different restrictions or guidelines for the type or size of images that appear. Images appearing in forms and lists will be automatically scaled by the platform. This requires a reference to another interface the component system understands (IImagePropertyRenderingInfo); and can be declared as shown in the following code fragment.
-<implementations> - <implementation> - <interface id="com.nokia.sdt.datamodel.adapter.IImagePropertyRenderingInfo"/> - <script file="MyComponent.js" prototype="MyComponent"/> - </implementation> -</implementations>-
The Attributes element allows you to declare miscellaneous characteristics about your component. For example, the following snippet is from the example Vertical Label .component files.
-<attributes> - <attribute key="cpp-class-name">CVerticalLabel</attribute> - <attribute key="rss-control-type-enum">EVerticalLabel</attribute> -</attributes>-
The cpp-class-name attribute is used by the source generation element (<sourceGen>) that is inherited from ControlCollectionItemBase. This allows you to specify the name of the C++ class to use in the generated source. The rss-control-type-enum attribute specifies the type identifier used in the QIK_CONTROL resource generated for the control in the control collection resource.
-Properties are the data values you can define for a component instance. The text property is the default text drawn by the vertical label component. Note that it is a localized string, so you may provide different values for each language added to the application. The lineWidth property determines the thickness of the border rectangle drawn around the component. A value of zero (0) indicates no border will be drawn. Note that default, minimum, and maximum values are specified. The default attribute is optional and provides an initial value. The optional minimum and maximum attributes provide range checking for integer properties.
-<properties> - <property name="text" type="localizedString" default="label"/> - <property name="lineWidth" type="integer" default="1" minValue="0" maxValue="5"/> -</properties>-
The <implementations> element is used in the VerticalLabel2.component example in order to render the component in the UI designer and provide its preferred size to be used by the layout manager. The <implementations> element informs the UI designer that the custom component has code. Implementations can be provided in either JavaScript or Java.
-Each implementation declaration has a list of one or more interfaces it fulfills. In this case the IVisualAppearance interface is implemented. This allows us to render an image corresponding to the current property values and provide feedback on the appropriate sizing for the component. The <script> element informs the UI designer which file has the script and the name of the JavaScript prototype object to instantiate, as shown in the following snippet.
-<implementations> - <implementation> - <interface id="com.nokia.sdt.datamodel.adapter.IVisualAppearance"/> - <script file="VerticalLabel.js" prototype="VerticalLabel"/> - </implementation> -</implementations>-
The example JavaScript file (VerticalLabel.js) contains an empty function to instantiate the JavaScript prototype. Note that the JavaScript file needs to be located as a sibling to the component file that references it.
-function VerticalLabel() {
- }
-The following code in the JavaScript file declares the draw method. It takes three parameters:
-VerticalLabel.prototype.draw = function(instance, laf, graphics) {
-The font object is obtained from the look and feel object. Since this is a simple example the font is hard-coded to a standard Symbian font.
-var font = laf.getFont("NormalFont");
- graphics.setFont(font);
-The background color needs to be set since anti-aliased text with a transparent background is drawn. In the UI Designer, each component is rendered into a bitmap with 'transparent pixel' support. The bitmap does not have an alpha channel. Thus, if the background color is not set, the 'transparent pixel' would be blended with the antialiased text, resulting in an orange border.
-graphics.setBackground(laf.getColor("EEikColorControlBackground"));
-Next a rectangular border and the text within the border is drawn. The bounds and position of the text are calculated accordingly.
-var properties = instance.properties; - var lineWidth = properties.lineWidth; - var halfLineWidth = lineWidth/2; - var textBounds = new Rectangle(halfLineWidth, halfLineWidth, - properties.size.width - halfLineWidth, - properties.size.height - halfLineWidth); - var x = lineWidth + 1; - var y = properties.size.height - lineWidth - 1;-
The rotated text is then drawn.
-graphics.drawRotatedString(properties.text, textBounds, x, y, -1.57, true);-
If requested, the border is drawn.
-if (lineWidth > 0) {
- graphics.setLineWidth(lineWidth);
- x = y = halfLineWidth;
-
- graphics.drawRectangle(x, y,
- properties.size.width-lineWidth,
- properties.size.height-lineWidth);
- }
-The getPreferredSize method is called by the layout manager to get the size of the component instance. If its text property is null, it will return an empty size, otherwise it will calculate the width of the text to use as its height, and return its parent's width as its width.
-VerticalLabel.prototype.getPreferredSize = function(instance, laf, wHint, hHint) {
- var text = instance.properties.text;
- if (text == null)
- return new Point(0, 0);
-
- var font = laf.getFont("NormalFont");
- var extent = TextRendering.formattedStringExtent(font, text, new Point(1000, 1000), 0, 0);
- var lineWidth = instance.properties.lineWidth;
- var parentBounds = instance.parent.getLayoutBounds();
-
- return new Point(parentBounds.width, extent.x + lineWidth + 1);
-}
-
-The Vertical Label component uses an RSS include file (example_verticallabel.rh). This file defines a custom resource used to initialize the component. Since our component uses a localized string it is especially important to use a resource. The <sourceMapping> element contains information on how to convert from property values to RSS statements, and from RSS statements back to property values.
-The <mapResource> element tells the RSS generator to create a resource of type EXAMPLE_VERTICAL_LABEL, and that the example_verticallabel.rh file is needed to create compilable source code. The RSS generator has flexible support for mapping properties to resources. Only simple conversions are needed, which can be done with the <mapSimpleMember> element. This has attributes that indicate a given property should be used to initialize a specific resource member. Refer to the "source mapping" XML schema documentation for details on all available mappings. Detailed documentation on the schema can be found in the plugins folder of your Carbide.c++ installation, for example, the default location at C:\Program Files\Nokia\Carbide.c++ v1.3\plugins\com.nokia.sdt.component.symbian_1.3.0.3. Also examine the UIQ components included with the UI designer for lots of examples; located at <Carbide installation path>/plugins/com.nokia.carbide.cpp.uiq.components/components.
-<sourceMapping> - <mapResource struct="EXAMPLE_VERTICAL_LABEL" headers="example_verticallabel.rh"> - <mapSimpleMember property="text" member="txt"/> - <mapSimpleMember property="lineWidth" member="line_size"/> - </mapResource> -</sourceMapping>-
The <sourceGen> element contains all the information needed to generate C++ code. Because this example is deriving from ControlCollectionItemBase, there is a lot of existing infrastructure to leverage. Source code generation is performed by executing JavaScript scripts. There is a layer above raw JavaScript that creates scripts by way of template expansion, like with PHP, JPS, ASP, etc. With templates you can define variables, or escape out to arbitrary script code. The following code snippet is from the Vertical Label .component files.
-
-<sourceGen>
- <useTemplateGroup ids="makeVisible"/>
- <templateGroup id="0" form="InstanceGen">
- <expandMacro name="SetupControlInstanceVariable" Type="${this.getCppClassName(instance)}"
- InstanceMemberName="${instanceMemberName}" InstanceTitle="${instanceName$title}"
- Headers="barsread.h eikenv.h"/>
- </templateGroup>
- <inline>
-if (Engine.formMatches(form, [""])) {
- // create files if missing
- Engine.createFromStockFile("inc", "VerticalLabel.h", "VerticalLabel.h");
- Engine.createFromStockFile("src", "VerticalLabel.cpp", "VerticalLabel.cpp");
-}
- </inline>
- <template phase="MainUserIncludes"><![CDATA[
-#include "VerticalLabel.h"
-#include "example_verticallabel.hrh"
-]]></template>
- <template location="VIEWDIALOGBASE_HEADER_OWNED_SYSTEM_INCLUDES"><![CDATA[
-#include <QikControlProvider.h>
-]]></template>
- <templateGroup id="ControlFactory">
- <template id="VerticalLabelControlFactory" phase="ClassPrivateOwnedMethods"><![CDATA[
-class TVerticalLabelControlFactory : public MQikControlFactory
- {
-public:
- CCoeControl* CreateByTypeL(
- TInt aType,
- TInt& aDefaultFlags )
- {
- if ( aType == EVerticalLabel )
- {
- aDefaultFlags = EQikCtrlFlagIsNonFocusing;
- return new(ELeave) CVerticalLabel;
- }
- return NULL;
- }
- CCoeControl* ConstructCustomControlL(
- TInt aUniqueHandle,
- TInt aType,
- TInt aResourceId,
- TInt aItemFlags,
- const CCoeControl& aParent )
- {
- return NULL;
- }
- };
-TVerticalLabelControlFactory iVerticalLabelControlFactory;
-]]></template>
- <template id="InstallControlFactory" phase="PreConstructFromResourceL"><![CDATA[
-// Install this factory in the control providers list
-ControlProvider()->AddControlFactoryL( iVerticalLabelControlFactory );
-]]></template>
- <template id="RemoveControlFactory" phase="Destroy"><![CDATA[
-// Remove this factory from the control providers list
-ControlProvider()->RemoveControlFactory( iVerticalLabelControlFactory );
-]]></template>
- </templateGroup>
-</sourceGen>
-
-Since source code generation is very detailed and specific, deriving from a component does not automatically enable source code generation. The derived component must specify what to generate, either completely or by referencing existing templates. Templates defined in ControlCollectionItemBase can be reused.
-The makeVisible template group does some standard initialization. Macros are groups of parametrized templates. The SetupControlInstanceVariable macro generates code to setup a member variable for the vertical label control's instance.
The <inline> element inserts JavaScript code. This example calls a predefined function to copy the stock versions of VerticalLabel.cpp and VerticalLabel.h that contain the runtime code implementing the vertical label control.
-There is a <template> element in this snippet that is used to define a new template in order to insert the #include "VerticalLabel.h" and #include "example_verticallabel.hrh" statements for the required header files.
-The final <templateGroup> element embodies a set of templates used to generate and install a custom control factory to translate the custom control type identifier, EVerticalLabel used in the control collection resource into a CVerticalLabel object.
The tutorial consists of two versions of the VerticalLabel component. VerticalLabel1 is the bare minimum needed to make a functioning component. VerticalLabel2 uses JavaScript to display the component in the UI Designer when designing your user interface.
+The following information explains what is relevant to the tutorial. Refer to the XML component schema documentation for all the details. +The root element for defining a custom component begins with the <componentDefinition> element as shown in the VerticalLabel1.component and VerticalLabel2.component files. It contains the necessary name space attributes, making the component schema namespace the default.
+The component element defines the majority of the component properties, attributes, source mapping and souce generation declarations. The following snippet is from the example .component files:
+<component friendlyName="%friendlyName" + qualifiedName="com.example.uiq.VerticalLabel1" + baseComponent="com.nokia.carbide.uiq.ControlCollectionItemBase" + category="Custom Controls" version="1.0" + instanceNameRoot="vlabel"> + <symbian + sdkName="com.uiq" minSDKVersion="3.0" + className="CVerticalLabel"/>+
Strings prefixed with % are localized strings that are automatically looked up in the accompanying properties files, such as VerticalLabel1.properties.
+Note that this component derives from ControlCollectionItemBase, which is a component included with Carbide.c++. It provides some of the source code generation, as well as allowing it to behave like the other UIQ controls in the UI designer in that they are used in a design's different layout configurations as references in the control collection.
+The <symbian> element specifies that this component is compatible with all SDKs from 3.0 forward and the class name in the VerticalLabel.cpp file used to draw the component at run time is CVerticalLabel.
+<symbian sdkName="com.uiq" minSDKVersion="3.0" className="CVerticalLabel"/>+
The sdkName property identifies the Symbian OS variant with which the component is compatible. Currently the only recognized SDK name for UIQ is "com.uiq".
+TIP Enter devices at a command prompt (C:\>devices) to display a list of installed and properly configured SDKs.
+In the VerticalLabel1 example, the <designerImages> element uses one image. This is the static layout image visible in the UI design. This is used in place of writing rendering script in a JavaScript file. You will only see a static graphic in the UI designer and its sizing by the current layout manager will not be defined by the component. Since icon images have also been omitted, default images are displayed in the palette and in the outline view. For example:
+<designerImages layoutImageFile="layoutImage.png"/>+
In the VerticalLabel2 example, the <designerImages> element uses custom icon images (.png files) to represent the component in the palette and outline views. The static layout image file can be removed since JavaScript rendering code has been added to display the component in the UI design. For example:
+<designerImages smallIconFile="VerticalLabel_sm.png" + largeIconFile="VerticalLabel.png"/>+
Images are validated and rendered on a per-component basis. Each component may have different restrictions or guidelines for the type or size of images that appear. Images appearing in forms and lists will be automatically scaled by the platform. This requires a reference to another interface the component system understands (IImagePropertyRenderingInfo); and can be declared as shown in the following code fragment.
+<implementations> + <implementation> + <interface id="com.nokia.sdt.datamodel.adapter.IImagePropertyRenderingInfo"/> + <script file="MyComponent.js" prototype="MyComponent"/> + </implementation> +</implementations>+
The Attributes element allows you to declare miscellaneous characteristics about your component. For example, the following snippet is from the example Vertical Label .component files.
+<attributes> + <attribute key="cpp-class-name">CVerticalLabel</attribute> + <attribute key="rss-control-type-enum">EVerticalLabel</attribute> +</attributes>+
The cpp-class-name attribute is used by the source generation element (<sourceGen>) that is inherited from ControlCollectionItemBase. This allows you to specify the name of the C++ class to use in the generated source. The rss-control-type-enum attribute specifies the type identifier used in the QIK_CONTROL resource generated for the control in the control collection resource.
+Properties are the data values you can define for a component instance. The text property is the default text drawn by the vertical label component. Note that it is a localized string, so you may provide different values for each language added to the application. The lineWidth property determines the thickness of the border rectangle drawn around the component. A value of zero (0) indicates no border will be drawn. Note that default, minimum, and maximum values are specified. The default attribute is optional and provides an initial value. The optional minimum and maximum attributes provide range checking for integer properties.
+<properties> + <property name="text" type="localizedString" default="label"/> + <property name="lineWidth" type="integer" default="1" minValue="0" maxValue="5"/> +</properties>+
The <implementations> element is used in the VerticalLabel2.component example in order to render the component in the UI designer and provide its preferred size to be used by the layout manager. The <implementations> element informs the UI designer that the custom component has code. Implementations can be provided in either JavaScript or Java.
+Each implementation declaration has a list of one or more interfaces it fulfills. In this case the IVisualAppearance interface is implemented. This allows us to render an image corresponding to the current property values and provide feedback on the appropriate sizing for the component. The <script> element informs the UI designer which file has the script and the name of the JavaScript prototype object to instantiate, as shown in the following snippet.
+<implementations> + <implementation> + <interface id="com.nokia.sdt.datamodel.adapter.IVisualAppearance"/> + <script file="VerticalLabel.js" prototype="VerticalLabel"/> + </implementation> +</implementations>+
The example JavaScript file (VerticalLabel.js) contains an empty function to instantiate the JavaScript prototype. Note that the JavaScript file needs to be located as a sibling to the component file that references it.
+function VerticalLabel() {
+ }
+The following code in the JavaScript file declares the draw method. It takes three parameters:
+VerticalLabel.prototype.draw = function(instance, laf, graphics) {
+The font object is obtained from the look and feel object. Since this is a simple example the font is hard-coded to a standard Symbian font.
+var font = laf.getFont("NormalFont");
+ graphics.setFont(font);
+The background color needs to be set since anti-aliased text with a transparent background is drawn. In the UI Designer, each component is rendered into a bitmap with 'transparent pixel' support. The bitmap does not have an alpha channel. Thus, if the background color is not set, the 'transparent pixel' would be blended with the antialiased text, resulting in an orange border.
+graphics.setBackground(laf.getColor("EEikColorControlBackground"));
+Next a rectangular border and the text within the border is drawn. The bounds and position of the text are calculated accordingly.
+var properties = instance.properties; + var lineWidth = properties.lineWidth; + var halfLineWidth = lineWidth/2; + var textBounds = new Rectangle(halfLineWidth, halfLineWidth, + properties.size.width - halfLineWidth, + properties.size.height - halfLineWidth); + var x = lineWidth + 1; + var y = properties.size.height - lineWidth - 1;+
The rotated text is then drawn.
+graphics.drawRotatedString(properties.text, textBounds, x, y, -1.57, true);+
If requested, the border is drawn.
+if (lineWidth > 0) {
+ graphics.setLineWidth(lineWidth);
+ x = y = halfLineWidth;
+
+ graphics.drawRectangle(x, y,
+ properties.size.width-lineWidth,
+ properties.size.height-lineWidth);
+ }
+The getPreferredSize method is called by the layout manager to get the size of the component instance. If its text property is null, it will return an empty size, otherwise it will calculate the width of the text to use as its height, and return its parent's width as its width.
+VerticalLabel.prototype.getPreferredSize = function(instance, laf, wHint, hHint) {
+ var text = instance.properties.text;
+ if (text == null)
+ return new Point(0, 0);
+
+ var font = laf.getFont("NormalFont");
+ var extent = TextRendering.formattedStringExtent(font, text, new Point(1000, 1000), 0, 0);
+ var lineWidth = instance.properties.lineWidth;
+ var parentBounds = instance.parent.getLayoutBounds();
+
+ return new Point(parentBounds.width, extent.x + lineWidth + 1);
+}
+
+The Vertical Label component uses an RSS include file (example_verticallabel.rh). This file defines a custom resource used to initialize the component. Since our component uses a localized string it is especially important to use a resource. The <sourceMapping> element contains information on how to convert from property values to RSS statements, and from RSS statements back to property values.
+The <mapResource> element tells the RSS generator to create a resource of type EXAMPLE_VERTICAL_LABEL, and that the example_verticallabel.rh file is needed to create compilable source code. The RSS generator has flexible support for mapping properties to resources. Only simple conversions are needed, which can be done with the <mapSimpleMember> element. This has attributes that indicate a given property should be used to initialize a specific resource member. Refer to the "source mapping" XML schema documentation for details on all available mappings. Detailed documentation on the schema can be found in the plugins folder of your Carbide.c++ installation, for example, the default location at C:\Program Files\Nokia\Carbide.c++ v1.3\plugins\com.nokia.sdt.component.symbian_1.3.0.3. Also examine the UIQ components included with the UI designer for lots of examples; located at <Carbide installation path>/plugins/com.nokia.carbide.cpp.uiq.components/components.
+<sourceMapping> + <mapResource struct="EXAMPLE_VERTICAL_LABEL" headers="example_verticallabel.rh"> + <mapSimpleMember property="text" member="txt"/> + <mapSimpleMember property="lineWidth" member="line_size"/> + </mapResource> +</sourceMapping>+
The <sourceGen> element contains all the information needed to generate C++ code. Because this example is deriving from ControlCollectionItemBase, there is a lot of existing infrastructure to leverage. Source code generation is performed by executing JavaScript scripts. There is a layer above raw JavaScript that creates scripts by way of template expansion, like with PHP, JPS, ASP, etc. With templates you can define variables, or escape out to arbitrary script code. The following code snippet is from the Vertical Label .component files.
+
+<sourceGen>
+ <useTemplateGroup ids="makeVisible"/>
+ <templateGroup id="0" form="InstanceGen">
+ <expandMacro name="SetupControlInstanceVariable" Type="${this.getCppClassName(instance)}"
+ InstanceMemberName="${instanceMemberName}" InstanceTitle="${instanceName$title}"
+ Headers="barsread.h eikenv.h"/>
+ </templateGroup>
+ <inline>
+if (Engine.formMatches(form, [""])) {
+ // create files if missing
+ Engine.createFromStockFile("inc", "VerticalLabel.h", "VerticalLabel.h");
+ Engine.createFromStockFile("src", "VerticalLabel.cpp", "VerticalLabel.cpp");
+}
+ </inline>
+ <template phase="MainUserIncludes"><![CDATA[
+#include "VerticalLabel.h"
+#include "example_verticallabel.hrh"
+]]></template>
+ <template location="VIEWDIALOGBASE_HEADER_OWNED_SYSTEM_INCLUDES"><![CDATA[
+#include <QikControlProvider.h>
+]]></template>
+ <templateGroup id="ControlFactory">
+ <template id="VerticalLabelControlFactory" phase="ClassPrivateOwnedMethods"><![CDATA[
+class TVerticalLabelControlFactory : public MQikControlFactory
+ {
+public:
+ CCoeControl* CreateByTypeL(
+ TInt aType,
+ TInt& aDefaultFlags )
+ {
+ if ( aType == EVerticalLabel )
+ {
+ aDefaultFlags = EQikCtrlFlagIsNonFocusing;
+ return new(ELeave) CVerticalLabel;
+ }
+ return NULL;
+ }
+ CCoeControl* ConstructCustomControlL(
+ TInt aUniqueHandle,
+ TInt aType,
+ TInt aResourceId,
+ TInt aItemFlags,
+ const CCoeControl& aParent )
+ {
+ return NULL;
+ }
+ };
+TVerticalLabelControlFactory iVerticalLabelControlFactory;
+]]></template>
+ <template id="InstallControlFactory" phase="PreConstructFromResourceL"><![CDATA[
+// Install this factory in the control providers list
+ControlProvider()->AddControlFactoryL( iVerticalLabelControlFactory );
+]]></template>
+ <template id="RemoveControlFactory" phase="Destroy"><![CDATA[
+// Remove this factory from the control providers list
+ControlProvider()->RemoveControlFactory( iVerticalLabelControlFactory );
+]]></template>
+ </templateGroup>
+</sourceGen>
+
+Since source code generation is very detailed and specific, deriving from a component does not automatically enable source code generation. The derived component must specify what to generate, either completely or by referencing existing templates. Templates defined in ControlCollectionItemBase can be reused.
+The makeVisible template group does some standard initialization. Macros are groups of parametrized templates. The SetupControlInstanceVariable macro generates code to setup a member variable for the vertical label control's instance.
The <inline> element inserts JavaScript code. This example calls a predefined function to copy the stock versions of VerticalLabel.cpp and VerticalLabel.h that contain the runtime code implementing the vertical label control.
+There is a <template> element in this snippet that is used to define a new template in order to insert the #include "VerticalLabel.h" and #include "example_verticallabel.hrh" statements for the required header files.
+The final <templateGroup> element embodies a set of templates used to generate and install a custom control factory to translate the custom control type identifier, EVerticalLabel used in the control collection resource into a CVerticalLabel object.
Carbide.c++ is built on the Eclipse platform. The Eclipse components used are:
-The APIs published by these components are available for use in your plugins.
-Carbide.c++ itself publishes a set of APIs which are documented in this guide.
-Carbide.c++ requires Java 5 and a Java 5 JRE is part of the Carbide.c++ installation. -Your plugins can use Java 5 features. The included version of CDT was built with Java 1.4 language compliance.
- -Developing plugins for Carbide.c++ requires knowledge of Java and Eclipse plugin development practices. -There are a number of good references in this area. Some are:
-Carbide.c++ is built on the Eclipse platform. The Eclipse components used are:
+The APIs published by these components are available for use in your plugins.
+Carbide.c++ itself publishes a set of APIs which are documented in this guide.
+Carbide.c++ requires Java 5 and a Java 5 JRE is part of the Carbide.c++ installation. +Your plugins can use Java 5 features. The included version of CDT was built with Java 1.4 language compliance.
+ +Developing plugins for Carbide.c++ requires knowledge of Java and Eclipse plugin development practices. +There are a number of good references in this area. Some are:
+This section will describe how to set up a basic Eclipse development environment -to develop a plugin against the Carbide.c++ development environment.
- -Carbide.c++ is developed against the Eclipse 3.4 release build which includes the Java Development Tools (JDT) and Plug-in Development Environment (PDE). You will need these items as well as the Carbide.c++/CDT source code to develop Eclipse/Carbide.c++ plug-ins. If you want to install the CDK you will need to run the Software Updates under the Help menu to update your installation to include the CDK.
-For more information on running the Software Updater please see the page Updating Carbide.c++.
-Once you have your Carbide environment updated to include the CDK, you can create new Eclipse plug-in projects and debug the Carbide.c++ sources. How to create eclipse plug-ins is beyond the scope of this demonstration. If you want to debug any of the Carbide.c++ or Ecilpse platform source follow these steps to verify your CDK isntallation:
-
This section will describe how to set up a basic Eclipse development environment +to develop a plugin against the Carbide.c++ development environment.
+ +Carbide.c++ is developed against the Eclipse 3.6 release build which includes the Java Development Tools (JDT) and Plug-in Development Environment (PDE). You will need these items as well as the Carbide.c++/CDT source code to develop Eclipse/Carbide.c++ plug-ins. If you want to install the CDK you will need to run the Software Updates under the Help menu to update your installation to include the CDK.
+For more information on running the Software Updater please see the page Updating Carbide.c++.
+Once you have your Carbide environment updated to include the CDK, you can create new Eclipse plug-in projects and debug the Carbide.c++ sources. How to create eclipse plug-ins is beyond the scope of this demonstration. If you want to debug any of the Carbide.c++ or Ecilpse platform source follow these steps to verify your CDK isntallation:
+ The information in this section will help you get started creating plug-ins for Carbide.c++. Topics in this section include:
-The information in this section will help you get started creating plug-ins for Carbide.c++. Topics in this section include:
+
Click OK, and you should now see the Carbide menu in the menu bar. You can now examine the source code and run it in the debugger. See debugging a debugging a Carbide.c++ plug-in for information on setting up a plug-in debug session.
- +