<!-- -*- xml-lite -*- -->
<refentry id="libmatecomponentui-faq" revision="1 Jan 2003">
    <refmeta>
	<refentrytitle>Common Questions</refentrytitle>
	<manvolnum>3</manvolnum>
	<refmiscinfo>Common Questions</refmiscinfo>
    </refmeta>
    
    <refnamediv>
	<refname>Common Questions</refname>
	<refpurpose>
	    Find answers to common questions in the libmatecomponentui manual
	</refpurpose>
    </refnamediv>
    
    <refsect1>
	<title>Questions and Answers</title>
	
	<para>
	    Frequently asked questions about the MateComponent UI Handler, version 0.1
	    by Michael Meeks &lt;michael@helixcode.com&gt;
	</para>
	
	<qandaset>
	    
	    <qandaentry>
		<question><para> How do I port my App from the old to
		    the new UI handler? </para> </question>
		<answer>
		    <para> If you have written a component, then ideally you should have
			to make no code changes, nor re-link the component. There is a
			compatibility layer that should just work. However, this exposes
			you to many evils of the old interface, and does strange things to
			paths for radio items etc.  If you have a complex UI you will want
			to re-write it. </para>
		    <para>
			If you have written a container, then again the changes are
			minimal, simply replace the mate_app calls with matecomponent_win
			calls. As long as you only used the matecomponent API to create menus you
			should be fine.  It is *important* that you replace the ui handler
			parameter to all calls to matecomponent_client_site_new_view to something
			of this form:</para>
		    <programlisting>
view_frame = matecomponent_client_site_new_view (
	MATECOMPONENT_CLIENT_SITE (site),
	matecomponent_ui_compat_get_container (ui_handler));
		    </programlisting>
		    <para> This is also true of the UI handler you pass to
			<programlisting>
matecomponent_widget_new_control (..., uih)
			</programlisting> and its variants.
		    </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>Where do I find examples ?</para></question>

		<answer><para> See samples/matecomponentui/hello.c which shows several ways of
		    constructing the UI. See also doc/ui-xml.txt. To build standard menus
		    copy items from std-ui.xml in the documentation.
		    </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para> How does translation work?</para></question>
		<answer>
		    <para>
			Every item has a non translated name which is used to construct a
			path for programmatic use. This is invariant over translations, it
			will often be similar to a label or verb name. User readable text
			is prefixed in the XML file by an '_', the file is parsed as it is
			read from disk and these '_' are removed as the strings are
			translated. </para>
		    <para> In order to extract translatable strings from a header file you
			need to use the 'matecomponent-ui-extract' utility which will be
			installed with matecomponent. Do:</para>
		    <command><literal>
			matecomponent-ui-extract my-app-ui.xml &gt; my-app-ui.h
			</literal></command>
		    <para>Ensure that you include my-app-ui.h in your POTFILES.in, but
			there is no need to include it in any files.</para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>Why don't you use XPath / XPointer?</para></question>
		<answer>
		    <para> These are fine reccomendations for addressing elements of an
			XML document. A major contributor to these reccomendations is my
			friend Daniel Velliard, with whom I discussed this issue. The UI
			handler primarily is designed to deal with an extremely dynamic
			XML structure.  The whole point of a path is to be invariant over
			XML (de)merges.  It transpires that XPath addressing
			eg. /menuitem[4] is not suitable for this situation. Hence an
			alternative, simple path scheme was implemented. </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>Where is the code for the UI handler?</para></question>
		<answer>
		    <para>
			See <filename>matecomponent-window</filename>,
			<filename>matecomponent-ui-xml</filename>,
			<filename>matecomponent-ui-container</filename>,
			<filename>matecomponent-ui-component</filename>,
			<filename>matecomponent-ui-toolbar</filename>,
			<filename>matecomponent-ui-item</filename>,
			<filename>matecomponent-ui-compat</filename></para>

		    <para> Do not see <filename>matecomponent-ui-handler</filename>,
			<filename>matecomponent-uih-menu</filename>,
			<filename>matecomponent-uih-toolbar</filename>
			<filename>matecomponent-uih-private</filename>. These are the old
			code. </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>
		    But what happens when Component Foo implements 'FileSave' and Component
		    Baa also implements 'FileSave'?</para> </question>
		<answer>
		    <para> The verbs are emitted on the component that registers them. In
			this case the verb gets sent to the component associated with
			whatever item was activated.</para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>I'm confused by paths,
		    where does the File menu live?</para></question>
		<answer>
		    <para>In the old strategy there was a partition of the menu vs.  other
			APIs, so a different paths trategy was used, in the old setup we
			would use:</para>
		    <programlisting>
		/File		[ old ]
		    </programlisting>

		    <para>In the new setup we use:</para>
		    <programlisting>
		/menu/File	[ new ]
		    </programlisting>

		    <para>Thus we can still use the same namespace for toolbars and other
			misc. items.</para>
		</answer>
	    </qandaentry>


	    <qandaentry>
		<question><para> What does this cmd / widget separation really mean?</para></question>
		<answer>
		    <formalpara><title>the plot:</title>
			<para>
			    Since we want to be able to allow the user to full customize
			    his or her menus and toolbars we need to be able to abstract
			    the following things away from the layout of the menus:
			    <para>
				sensitivity, hiddenness, state ( such as toggledness )
			    </para>
			    Other things we want to separate are:
			    <para>
				default labels, tips and pixmaps</para>
			</para>
		    </formalpara>

		    <formalpara><title>
			So; how is this separation achieved in practice?</title>

			<para>
			    We have a namespace that 'commands' live in; these can either
			    be things like 'Save' ( a verb ) or 'Threaded View' ( a state
			    with an id ). Both verbs and id's are in the same space. So;
			    we describe the capbilities of a program in terms of the verbs
			    and state inputs it can handle, and provide a default UI
			    layout, perhaps like this:
			    <programlisting>
&lt;Root&gt;
	&lt;commands&gt;
		&lt;cmd name="baa" _label="Our Label" _tip="Hello World"
		 pixtype="stock" pixname="Open"/&gt;
	&lt;/commands&gt;
	&lt;menu&gt;
		&lt;menuitem name="foo" verb="baa"/&gt;
	&lt;/menu&gt;
&lt;/Root&gt;
			    </programlisting>

			    Now; the user can chose to remove the 'Our Label' button, or
			    more creatively might decide to convert it into a toolbar and
			    change the label to 'MyLabel':
			    <programlisting>
-	&lt;menu&gt;
-		&lt;menuitem name="foo" verb="baa"/&gt;
-	&lt;/menu&gt;
+	&lt;dockitem name="fishy"&gt;
+		&lt;toolitem name="foo" verb="baa" _label="MyLabel"/&gt;
+	&lt;/dockitem&gt;
			    </programlisting>
			</para>
		    </formalpara>

		    <formalpara><title> But what does this mean for the programmer? </title>
			<para>
			    What it means, is that when you decided to make this (
			    dangerous lookin ) verb insensitive, instead of setting
			    sensitive="0" on the item at path /menu/foo, you instead do it
			    on the item at path /commands/baa. This then allows the user
			    to have none, one or many representations of each verb/id as
			    either menu or toolbar items.</para>
		    </formalpara>

		    <formalpara><title> But wait, don't you need Menu_Open for stock menu
			icons? </title>
			<para>
			    In this case no; since we need to be able to generate either a
			    menu or a toolbar item view of this verb/id. Consequently the
			    code will add the Menu_ prefix where needed for you.
			</para>
		    </formalpara>

		    <formalpara><title> But wait, what if the stock items are called
			Foo_Open and Baa_Open for menu / toolbar items ? or ... what if I
			have a non-stock toolbar icon that won't fit in a menu ? </title>
			<para>
			    Sadly there was not time to implement custom widget sizing
			    logic, so setting a single pixmap on the verb won't
			    work. However, you can still set the pixmap on the individual
			    toolbar / menu items at the expense of customization.</para>
		    </formalpara>

		    <formalpara><title> But what about acclerators ?
			How do I get rid of '_'s in my toolbar labels. </title>

			<para>
			    Since accelerators are clearly part of the widget and not the
			    command it is important to put labels with accelerators in
			    them in the widget and not the command node. _But_ it is also
			    important to ensure that a non-accelerated version is left in
			    the command for use by GUI configuration software as a default
			    label, it would also be wise to use this as the default
			    toolbar label. So this is good practice:
			    <programlisting>
&lt;Root&gt;
	&lt;commands&gt;
	        &lt;cmd name="FileOpen" _label="Open" hidden="1"
		_tip="Open a file" pixtype="stock" pixname="Open"
		accel="F3"/&gt;
	&lt;/commands&gt;

	&lt;menu&gt;
	        &lt;menuitem name="FileNew" verb="" _label="_New"/&gt;
	&lt;/menu&gt;
&lt;/Root&gt;
			    </programlisting>

			    See std-ui.xml for a set of correctly organised useful cmd and
			    widget descriptions.
			</para>

			<para>
			    Note that 'verb=""' is shorthand for making the verb name the
			    same as the node name (in this example, "FileNew"). This is
			    not the same as leaving the verb out entirely. </para>
		    </formalpara>
		</answer>
	    </qandaentry>

<!-- I removed this faq entry since it no longer applies in Mate 2.x. -->		
<!-- * When I look at the xml being transfered I see that many elements -->
<!--   show up as hex strings; why is this ? -->
<!-- * I get a warning saying that something is not correctly encoded, -->
<!--   what does that mean ? -->
		<!-- ...etc... -->

	    <qandaentry>
		<question><para> Why don't my old non-alphanumeric keyboard accelerators
		    work anymore? </para> </question>
		<answer>
		    <para>
			Keyboard accelerators are now specified in ItemFactory format,
			e.g.  "*Control*s". In old MateComponent, you would have passed 'S' to
			specify the character. For alphanumeric keys, this translation is
			obvious and hard to get wrong. But for non-alphanumeric keys, you
			now have to use the symbolic name returned by gdk_keyval_name
			(which in turn is the symbolic name returned by
			XKeysymToString). For example, to specify Control-equal-sign as a
			keyboard accelerator now, you use "*Control*equal". "*Control*="
			will silently fail to do anything useful.
		    </para>
		    <para>
			Standard KeySym names are obtained from &lt;X11/keysymdef.h&gt; by
			removing the XK_ prefix from each name.</para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>Why do the menu bar titles
		    flash when merging occurs?</para></question>
		<answer>
		    <para>
			They flash if the &lt;submenu&gt; node has been redefined, or if
			MateComponent thinks it has been. A common cause for this is to define
			the label for the menu in more than one place. MateComponent will not
			recognize that &lt;submenu name="File" _label="File"&gt; is
			identical to a submenu already defined exactly the same way
			elsewhere. If you're adding items to an existing menu, don't
			redefine the label; refer to the existing submenu node by name
			only, e.g. &lt;submenu name="File"&gt;. Note that in addition to
			flashiness this can also cause torn-off menus to hide themselves.
		    </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para>Surely the radio group belongs on the Verb !?
		    </para></question>
		<answer>
		    <para>
			Due to the way the group="whatever" works, it is not possible to
			have the group set on the command, there can of course be mutiple
			sets of the same radio verbs, but they cannot share the same
			group.
		    </para>
		</answer>
	    </qandaentry>

 
	    <qandaentry>
		<question><para>How do I let the user customize a toolbar once it's hidden?
		    </para></question>
		<answer>
		    <para>You really want to add a menu item with the builtin verb
			'MateComponentCustomize' that should magically do what you want.
		    </para>
		</answer>
	    </qandaentry>

	    <qandaentry>
		<question><para> In a UI file I have two &lt;menu&gt; elements, and the
		    menu items inside the second &lt;menu&gt; do not show up in the
		    application. What's wrong? </para> </question>
		<answer>
		
		    <para>
			You have to put all menu items in a UI file in a single
			&lt;menu&gt; element. Instead of this: </para>
		    <programlisting>
&lt;menu&gt;
    &lt;menuitem foo/&gt;
&lt;/menu&gt;
&lt;menu&gt;
    &lt;menuitem foo2/&gt;
&lt;/menu&gt;
		    </programlisting>
		    <para>Use this:</para>
		    <programlisting>
&lt;menu&gt;
    &lt;menuitem foo/&gt;
    &lt;menuitem foo2/&gt;
&lt;/menu&gt;
		    </programlisting>
		</answer>
	    </qandaentry>
	    
	</qandaset>
    </refsect1>
</refentry>

