.. include:: vars.rst .. _section-tutorials: Tutorials ********* This chapter describes several examples, all of which require a Project. You can create your own Project by following :numref:`section-creating-new-project`. Defining Your Data Type ^^^^^^^^^^^^^^^^^^^^^^^^ This example shows how to define your own data type using |SD|. In this example, we are going to create the ShapeTypeExtended data type used by the Shapes Demo: .. code-block:: idl enum ShapeFillKind { SOLID_FILL, TRANSPARENT_FILL, HORIZONTAL_HATCH_FILL, VERTICAL_HATCH_FILL }; struct ShapeType { string<128> color; //@key long x; long y; long shapesize; };//@Extensibility EXTENSIBLE_EXTENSIBILITY struct ShapeTypeExtended : ShapeType { ShapeFillKind fillKind; float angle; };//@Extensibility EXTENSIBLE_EXTENSIBILITY #. Create a new project (see :numref:`section-creating-new-project`), name it ShapesDemo, and click OK. .. figure:: static/create_new_project.png :alt: Creating a new project :name: Figure_create_new_project :align: center :figwidth: 90% #. Go to the Types View. By default it should be the first view shown by |SD|. |br| |br| #. Add an enumeration by right-clicking on Types and selecting **Add Enumeration...** Name your enumeration 'ShapeFillKind' and click OK. |br| |br| #. Right-click on the recently created enum and select **Add Member...** to start adding each one of the following four enumerator value names: SOLID_FILL, TRANSPARENT_FILL, HORIZONTAL_HATCH_FILL, and VERTICAL_HATCH_FILL. You can leave the Value blank and @default_literal unchecked. .. figure:: static/shape_fill_kind_enumerator.png :alt: ShapeFillKind enumerator values :name: shape_fill_kind_enumerator :align: center :figwidth: 90% #. Create a struct and name it 'ShapeType' by right-clicking on Types and selecting **Add Struct...** Select APPENDABLE as its @extensibility value and click OK. Fill the struct, adding each member by right-clicking on the struct and selecting **Add Member...**: - Add a bounded (128) string named 'color'. This element will be the key of our type, so select the @key checkbox. (You can accept the other defaults in this window.) |br| |br| - Add three longs named 'x', 'y' and 'shapesize'. Although 'long' is not in the list of suggestions for the Type field, you can type it in. Or use the newer int32 instead of long. See :ref:`section-working-with-types`. |br| |br| #. Create a second struct and name it 'ShapeTypeExtended'. Choose ShapeType as its base type. Add its elements by right-clicking on the struct and selecting **Add Member...**: - Add a ShapeFillKind enumerator named 'fillKind'. |br| |br| - Add a float32 named 'angle'. When the type definition is complete, you can download the IDL by clicking on the Download IDL button in the IDL view. .. figure:: static/download_idl.png :alt: Downloading idl :name: donwload_idl :align: center :figwidth: 90% Now you have an IDL file to use to create your own Shapes Demo application. Defining an XML Application Creation Configuration File ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example shows how to define an XML configuration file using |SD|. In this example, we are going to create the same configuration file used by the **hello_world_xml_dynamic** example. For more information about XML-Based Application Creation, see the :link_xml_app_creation:`RTI Connext DDS Core Libraries XML-Based Application Creation Getting Started Guide <>`. #. Create a new XML file inside the open Project by clicking the Files icon at the top and selecting **New...** You can use the same project as you used in the previous tutorial, or a new project. Name the file USER_QOS_PROFILES.xml. Click OK. .. note:: If you see a default XML file already associated with the project, that's because you kept the default selection, "Automatically create an empty XML file" when you created the project. You can still create USER_QOS_PROFILES.xml, it will not replace the default one. #. Go to the Types View. By default it should be the first view shown by |SD|. |br| |br| #. Add two constants (right-click Types > **Add Constant...**) as follows: - Name 'MAX_NAME_LEN', Type 'long', value 64, File USER_QOS_PROFILES.xml |br| |br| - Name 'MAX_MSG_LEN', Type 'long', value 128, File USER_QOS_PROFILES.xml .. figure:: static/max_name_length_constant.png :alt: Defining constant :name: max_name_length_constant :align: center :figwidth: 90% #. Create a struct (right-click Types > **Add Struct...**) and name it 'HelloWorld.' Fill the struct by adding each of the following members (right-click on the struct and select **Add Member...**): - Add a bounded string named 'sender' with a maximum length of MAX_NAME_LEN. (For this and the following members, you can accept the defaults in the window.) |br| |br| - Add a second bounded string named 'message' with a maximum length of MAX_MSG_LEN. .. figure:: static/bounded_string.png :alt: Defining bounded string :name: bounded_string :align: center :figwidth: 90% - Add a long named 'count'. |br| |br| #. Click the XML view to view how your data type definition looks in XML: .. figure:: static/helloworld_type.png :alt: Defining Hello World :name: helloworld_type :align: center :figwidth: 90% #. Define the QoS that the application is going to use by clicking on the QoS view. Since we are creating the same XML file as the **hello_world_xml_dynamic** example has, to match the content of that file you only need to add a new QoS Library named 'qosLibrary' and a QoS Profile named 'DefaultProfile' inside the created libray. (You do not have to select any of the checkboxes.) In the XML view, your QoS Profile should look like this: .. figure:: static/default_profile.png :alt: Defining QoS :name: default_profile :align: center :figwidth: 90% #. Now that the QoS has been defined, define the system's Topic and its corresponding data types, first by defining the Domain: - In the Domain view, right-click on Domain Libraries and select **Add Library**. Name your domain 'MyDomainLibrary' and click OK. .. note:: If your project contains more than one XML file, select the USER_QOS_PROFILES.xml file. - Add a domain to your library by right-clicking MyDomainLibrary and selecting **Add Domain**. Name it 'HelloWorldDomain,' entering 0 as its Domain Id. |br| |br| - Select HelloWorldDomain and click the **Add** button to add a registered type. Name the type 'HelloWorldType,' selecting the 'HelloWorld' struct that we created previously as its type reference. .. figure:: static/register_type.png :alt: Defining type :name: register_type :align: center :figwidth: 90% - In the Topics panel, click the **Add** button to add a topic named 'HelloWorldTopic,' selecting the 'HelloWorldType' registered type as its registered type reference. .. figure:: static/register_topic.png :alt: Defining topic :name: register_topic :align: center :figwidth: 90% In the XML view, your domain configuration should look like this: .. figure:: static/domain_definition.png :alt: Defining Domain :name: domain_definition :align: center :figwidth: 90% #. Define the elements that are going to be part of our system by clicking on the Participant view. In this example, we are going to create a simple application containing one DomainParticipant, one Publisher, one Subscriber, one DataReader, and one DataWriter. - Add a new Participant Library, naming it 'MyParticipantLibrary.' Add a Participant inside that library named 'PublicationParticipant,' selecting the previously created 'MyDomainLibrary::HelloWorldDomain' as its domain reference. .. note:: If your project contains more than one XML file, select the USER_QOS_PROFILES.xml file. .. figure:: static/creating_participant.png :alt: Defining Participant :name: creating_participant :align: center :figwidth: 90% - Click the **Add** button to add a publisher named 'MyPublisher.' |br| |br| - Click the **Add** button to add a DataWriter named 'HelloWorldWriter,' selecting 'HelloWorldTopic' as its topic reference. .. figure:: static/defining_writer.png :alt: Defining Writer :name: defining_writer :align: center :figwidth: 90% - Add a second Participant inside that library named 'SubscriptionParticipant,' selecting the previously created 'MyDomainLibrary::HelloWorldDomain' as its domain reference. |br| |br| - Click Subscriptions and add a subscriber named 'MySubscriber.' |br| |br| - Add a DataReader named 'HelloWorldReader,' selecting 'HelloWorldTopic' as its topic reference. Unlike for the DataWriter, for the DataReader we are going to select the QoS profile that we created earlier, named DefaultProfile (in the Default QoS): click on View/Edit inside the DataReader dialog and name the QoS Profile 'HelloWorld_reader_qos'. Select 'qosLibrary::DefaultProfile' as its Base QoS. .. figure:: static/reader_qos_definition.png :alt: Defining DataReader QoS :name: reader_qos_definition :align: center :figwidth: 90% #. Your XML view should look like this: .. figure:: static/participant_definition.png :alt: Defining Participant :name: participant_definition :align: center :figwidth: 90% You can use this XML file to define your *Connext DDS* system using XML-Based Application Creation.