/*! \page toolbarxml Toolbar Widget XML Specification
<b>Version</b>: 0.1

\section Overview
This document describes the XML specification of the toolbar widget.

\sa MToolbarData

\section Tags
\subsection INPUT-METHOD
Root tag, it contains information which should be used by input method plugin.
The VERSION attribute defines version of this specification. Current version is 1.
Warning: you need to specify version number explicitly, otherwise parser may assume wrong version number and then parsing will fail.
The VISIBLE attribute defines toolbar's visibility. Toolbar is visible by default, but you could hide it by setting VISIBLE to false.
Warning: normal application should not use this attribute.
The REFUSE attribute enumerates names of standard items which should not be added to your toolbar. Names should be separated by commas without spaces. See also "Standard toolbar items".

\subsection TOOLBAR
It contains the definition for all items in the toolbar.
TOOLBAR tag could be used as root tag for backward compatibility.
This tag have same attributes as INPUT-METHOD.

\subsection ITEMS
This tag contains definitions of all items which will be placed into layouts.

\subsubsection BUTTON
This tag will be constructed as MButton.
The NAME attribute is used as a reference in the toolbar system.
All buttons with the same NAME share their state. If two buttons have the same name then their state is defined by first one and then overriden (completely or partially) by second one. This feature allows to have consistent button state with different device orientation. All names starting with underscore are reserved for Input Method Framework.
Warning: it is not recommended to create more than one button with the same name inside one layout.
The GROUP attribute defines the group this button belongs to.
The SHOWON attribute tells when the button is displayed. If the value is "selectedtext", it will be only displayed when there is a selected text. If the value is "always" then it is always displayed.
Similar rule applies with HIDEON attribute, except that there is no "always" value.
Buttons can be aligned within toolbar by using the ALIGNMENT attribute. By default, buttons are center-aligned. Possible other alignments are left or right.
The ICON attribute holds the icon file name (absolute file name). The icon will be displayed in the center of the button.
The SIZE attribute holds the icon size percentage. The icon will be resized according this attribute and the button size.
The ICON_ID attribute holds the icon logical id to be displayed on button. ICON_ID has higher priority than ICON, so if both ICON and ICON_ID are specified, ICON_ID will be used. Note: only the ICON_ID of the icons loaded by meegotouch theme will be used.
The TEXT attribute holds the text and TEXT_ID holds the logical id of the text.
The TOGGLE attribute defines the type of the button whether it is a toggle button or not, by default the value is false.
If the TOGGLE attribute is true, the PRESSED attribute holds the button state whether the button is pressed or not.
The HIGHLIGHTED attribute selects which background image should be used.
The ENABLED attribute holds whether the button is enabled. Default value is true. If it is set to false, the button will be disabled.
The VISIBLE attribute defines the button's visibility. Normally, application does not need to specify this attribute. The button is visible by default, but application could hide it by setting VISIBLE to false. This attribute will override the SHOWON and HIDEON.
Text inside button is always center-aligned.

\subsubsection LABEL
This tag will be constructed as MLabel.
LABEL tag could have following attributes: NAME, GROUP, VISIBLE, SHOWON, HIDEON, ALIGMENT, TEXT and TEXT_ID.
Every attribute has the same meaning as for BUTTON tag.
Text inside labels can be horizontally aligned by using the CONTENT-ALIGNMENT attribute. By default, label text is center-aligned. Possible other content alignments are left or right.

\subsubsubsection ACTIONS
This tag holds a sequence of actions defined within.

\subsubsubsubsection SENDKEYSEQUENCE
The tag's value holds the key sequence to be sent in the format which is understood by QKeySequence to the text entry widget.

\subsubsubsubsection SENDSTRING
The tag's value holds the string to be sent to the text entry widget as committed text.

\subsubsubsubsection SENDCOMMAND
The tag's value holds the command to be sent to the text entry widget. The command would be widget specific.

\subsubsubsubsection SHOWGROUP
This tag defines that the action is to show the named group of buttons.

\subsubsubsubsection HIDEGROUP
This tag defines that the action is to hide the named group of buttons.

\subsubsubsubsection COPY
This tag defines that the action is to copy selected text.

\subsubsubsubsection PASTE
This tag defines that the action is to paste from clipboard.

\subsubsubsubsection CLOSE
This tag defines that the action is to close keyboard and removes focus from active text entry.

\subsection Layout

Layout describes the actual toolbar layout for a given screen orientation.  If the layout doesn't have a portrait variant, the software shall use the landscape variant when the device is in portrait orientation. Each layout contains one row only.

\subsubsection Row

This tag defines one row in toolbar.
It is not recommended to create more than one row for landscape orientation.
Row may not be empty.
Warning: this tag is deprecated and will be removed soon, because toolbar should have one row only.

\subsubsection Item

This tag defines which item should be placed into toolbar.
NAME attribute selects correspondig item (button or label) which is defined in the Items section.

\section Standard toolbar items
Button "_close" closes keyboard and removes focus from active text entry. This button is right aligned.
Button "_copypaste" copies selected text (if any) or pastes current clipboard content. This button is left aligned.
Warning: you can use REFUSE to remove standard toolbar items. But you should not change the attributes of standard toolbar items.

\section DTD
\code
<!DOCTYPE MEEGO_INPUT_METHOD [
<!ELEMENT input-method (toolbar)>
<!ELEMENT toolbar (items,layout+)>
<!ELEMENT items ((button|label)+)>
<!ELEMENT layout (item+)>
<!ELEMENT button (actions*)>
<!ELEMENT actions (sendkeysequence|sendstring|sendcommand|copy|paste|showgroup|hidegroup|close)*>
<!ELEMENT sendkeysequence (#CDATA)>
<!ELEMENT showgroup (#CDATA)>
<!ELEMENT hidegroup (#CDATA)>
<!ELEMENT copy EMPTY>
<!ELEMENT paste EMPTY>

<!ATTLIST input-method version (0|1) "0">
<!ATTLIST input-method visible (true|false) "true">
<!ATTLIST input-method refuse CDATA "">

<!ATTLIST toolbar version (0|1) "0">
<!ATTLIST toolbar visible (true|false) "true">
<!ATTLIST toolbar refuse CDATA "">

<!ATTLIST layout orientation (landscape|portrait) "landscape">

<!ATTLIST button name CDATA #REQUIRED>
<!ATTLIST button group CDATA>
<!ATTLIST button showon (selectedtext|always)>
<!ATTLIST button hideon (selectedtext)>
<!ATTLIST button alignment (left|right|center) "center">
<!ATTLIST button icon CDATA "">
<!ATTLIST button size CDATA "">
<!ATTLIST button icon_id CDATA "">
<!ATTLIST button text CDATA "">
<!ATTLIST button text_id CDATA "">
<!ATTLIST button toggle (true|false)>
<!ATTLIST button pressed (true|false)>
<!ATTLIST button highlighted (true|false) "false">
<!ATTLIST button enabled (true|false) "true">

<!ATTLIST label name CDATA #REQUIRED>
<!ATTLIST label group CDATA>
<!ATTLIST label showOn (selectedtext|always)>
<!ATTLIST label hideOn (selectedtext)>
<!ATTLIST label alignment (left|right|center) "center">
<!ATTLIST label text CDATA "">
<!ATTLIST label text_id CDATA "">
<!ATTLIST label content-alignment (left|right|center) "center">

<!ATTLIST sendkeysequence keysequence CDATA>
<!ATTLIST sendstring string CDATA>
<!ATTLIST sendcommand command CDATA>
<!ATTLIST showgroup group CDATA>
<!ATTLIST hidegroup group CDATA>

<!ATTLIST item name CDATA #REQUIRED>
]>
\endcode
*/
