GCF Content XML File Specification

Table of Contents

• Element hierarchy
• content XML element
• object XML element
  • parent attribute
  • allowmetaaccess attribute
• property XML element
• connection XML element

Components can offer a content file for loading while handling the pre-content-load event in GCF::Component::contentLoadEvent(). The content file is a XML file whose primary purpose is to provide a list of objects that need to be loaded during GCF::Component::load(). A typical content file would look like this

<content>

    <object name="a" />
    <object name="b" />
    <object name="c" />
    <object name="d" />

</content>

Basically the content-file contains content XML element as root and a series of object XML elements. Each object XML element must have a name attribute, otherwise it is ignored by GCF. Object names must be unique within the component, otherwise GCF will attempt to make it unique by adding some characters at the end of the name.

The object XML element can contain additional attributes, some of which have implicit meanings. This page provides the complete file specification of a content-xml file.

Element hierarchy

The content XML file accepts the following element hierarchy

• content
  • object
    • property
    • connection

Attributes of all XML elements are case-insensitive. GCF converts attribute names to lower case after parsing the XML file.

content XML element

The content XML element is the root of all elements in a content-xml file. This XML element has no attributes of interest. Any attribute specified for this XML element will be left ignored. There should be only one content XML element in a content-file.

object XML element

object XML element is a direct child of the content XML element. Each object XML element declares the existence of one single named object in the component. The object XML element can have any number of attribtues. Attribute names are case-insensitive. But values are not.

One attribute that MUST be mentioned in the object XML element is the name attribute. This attribute's value must be a unique name within the component, or atleast the content-xml file.

When GCF processes the object XML element, it sends a GCF::ContentObjectLoadEvent to the component. Along with this event GCF will send the value of the name attribute and a key=value map of all other attributes in the object XML element. This map will have all its keys in lower-case letters.

The GCF::ContentObjectLoadEvent::name() function will return the value of the name attribute in the object XML element. The GCF::ContentObjectLoadEvent::info() function will return a QVariantMap of key=value pairs. Each pair is a attribute=value pair in the object XML element. [NOTE: values for attributes name and parent will not be available from info()]

A component can handle this event in its GCF::Component::contentObjectLoadEvent() implementation to

• actually load the object (as a QObject instance)
• Use the GCF::ContentObjectLoadEvent::setObject() method on the event object, passed as parameter to the event handler, to send back pointer to the QObject that was just loaded

In GCF, we have three major component classes: GCF::Component, GCF::QmlComponent and GCF::GuiComponent. Each of these classes have their own implementation of contentObjectLoadEvent()contentObjectLoadEvent().

• The contentObjectLoadEvent() function implementation in GCF::Component simply request for loadObject() to load a named object and returns a pointer to that via setObject() method.

• The contentObjectLoadEvent() function implementation in GCF::GuiComponent looks for value of the type attribute.
  • If type is "widget" then it invokes the loadWidget() virtual function to create a QWidget.
  • If type is "action" then it invokes the loadAction() virtual function to create a QAction.
  • If type is "menu" then it invokes the loadMenu() virtual function to create a QMenu.
  • If type is "actiongroup" then it invokes the loadActionGroup() virtual function to create a QActionGroup.
  • If type is "toolbar" then it invokes the loadToolBar() virtual function to create a QToolBar.
  • If type is "menubar" then it invokes the loadMenuBar() virtual function to create a QMenuBar.
  • For all other types, GCF::Component::contentObjectLoadEvent() is called. Which in-turn calls loadObject()

• The contentObjectLoadEvent() function implementation in GCF::QmlComponent looks for value of the type attribute. If the value of the type attribute is "qml" then, it looks for the value of the url attribute. The class then loads a .qml file available at the URL specified in the url attribute. The URL attribute could contain a .qml file URL for loading from
  • a HTTP location. Example: http://something.com/folder/MyCoolItem.qml
  • a FTP location. Example: ftp://something.com/folder/MyCoolItem.qml
  • local file system
    • Example: file:///Users/username/folder/MyCoolItem.qml
    • Example: ../../folder/MyCoolItem.qml
  • a QRC location. Example: qrc://Folder/MyCoolItem.qml

parent attribute

After the GCF::Component::contentObjectLoadEvent() returns, GCF looks for value of the parent attribute in the object XML element. The value of parent attribute has to be a path to an already registered object in the application. If the path corresponds to an object owned by another component, then a GCF::ContentObjectMergeEvent is sent to that component. This event can be handled in the GCF::Component::contentObjectMergeEvent() to perform object-merging. Components can customize the way in which merging happens.

• The contentObjectMergeEvent() implementation in GCF::Component class simply makes use of the QObject::setParent() method to merge child into parent.

• The contentObjectMergeEvent implementation in GCF::GuiComponent class looks for the type attribute associated with the parent and takes an appropriate action.
  • if parent type is widget - mergeWithWidget() is called. Note if the child is not a widget, then contentObjectMergeEvent is called.
  • if parent type is actiongroup - mergeWithActionGroup(). Note if the child is not a QAction, then contentObjectMergeEvent() is called.
  • if parent type is menu - mergeWithMenu() is called.
  • if parent type is toolbar - mergeWithToolBar() is called.
  • if parent type is menubar - mergeWithMenuBar() is called.

• GCF::QmlComponent's implementation of contentObjectMergeEvent() ignores merging between two QML objects. This means that if the type attribute of both parent and child is "qml", then the merging is ignored.

allowmetaaccess attribute

Each object XML element can have an optional allowMetaAccess attribute. This attribute can have a value of "true" or "false". If no such attribute is specified, then the value is assumed to be "false" by default.

The value of this attribute is checked when a method or property on this object is accessed during an IPC call. If the value of this attribute is "false", then the IPC call will be aborted.

Read IPC module in GCF for more information on IPC.

property XML element

The property XML element can be used to set the property of an object upon its creation and it can have the following child XML elements.

• key
• value

The key XML element should contain name of the property that needs to be set. The value XML element should contain the value of the property that needs to be set. You can use this to set int, bool, double, QString, and QByteArray properties only.

Example:

<content>

    <object name="window">
        <property>
            <key>windowTitle</key>
            <value>title string for the window</value>
        </property>
    </object>

</content>

connection XML element

The connection XML element can be used to establish a signal slot connection between the object in question and any other object in the application. The rule here is that either the sending signal or the receiving slot/member MUST belong to the object in question. You cannot use the connection XML element to establish signal/slot connections between two random objects.

The connection XML element can have the following child XML elements.

• sender
• receiver

The text specified for either sender or receiver XML element can be in the following format

{Component}.{Object}::{MemberSignature}

• if {Component} is not specified, then the object is considered to be from this component.

• if both {Component} and {Object} are not specified, then the method is considered to belong to the object in question (referred to by the enclosing object XML)

Example:

<content>

    <object name="CalendarWidget"
            parent="Application.BaseComponent.Window">

        <connection>
            <sender>clicked(QDate)</sender>
            <receiver>Application.DateEdit.DateEditWidget::setDate(QDate)</receiver>
        </connection>

        <connection>
            <sender>Application.DateEdit.DateEditWidget::dateChanged(QDate)</sender>
            <receiver>setSelectedDate(QDate)</receiver>
        </connection>

    </object>

</content>