cmd / widget separation ...

[Michael Meeks <michael helixcode com>]

Hi Guys,

	I just finished the cmd / widget separation and a few other
minor changes to the UI code that neccessitate a couple of seds on
your ui xml files, and optional ( but much recommended ) slight
re-structuring of listener code.

	The seds are:

		s/descr=/tip=/
		s/"Menu_/"/	

	And to understand the listener reccommendation read on from
the new FAQ entry.

* What does this cmd / widget separation really mean ?

** the plot:

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:

	sensitivity, hiddenness, state ( such as toggledness )

Other things we want to separate are:

	default labels, tips and pixmaps

** So; how is this separation achieved in practice ?

	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:

<Root>
	<commands>
		<cmd name="baa" _label="Our Label" _tip="Hello World"
		 pixtype="stock" pixname="Open"/>
	</commands>
	<menu>
		<menuitem name="foo" verb="baa"/>
	</menu>
</Root>

	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':

-	<menu>
-		<menuitem name="foo" verb="baa"/>
-	</menu>
+	<dockitem name="fishy">
+		<toolitem name="foo" verb="baa" _label="MyLabel"/>
+	</dockitem>

** But what does this mean for the programmer ?

	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.

** But wait, don't you need Menu_Open for stock menu icons ?

	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.

** 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 ?

	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.

	Regards,

		Michael.

-- 
 mmeeks gnu org  <><, Pseudo Engineer, itinerant idiot