kdevelop actions

[Simon Hausmann]

On Thu, 22 Jun 2000, Falk Brettschneider wrote:

> > Falk, could you discuss things with
> > Simon about KParts ? He´s definitely the expert here and can tell you
> > the details about the konqueror design as an example for the class
> > structure to be used.
> 
> OK, hi Simon, can you hear me? ;-)

I do :-) In fact the kdevelop-kparts integration was the reason why I
subscribed here :-)

> I've got a problem with the dynamism of the XML menu description. You know, Ralf
> created a kdevelop.rc file that contains an XML-based data description of the
> menus in KDevelop. As I understand that right, the file is parsed by KParts&Co. on
> application startup. Well, all works fine except until we do more than that
> statical menu creation. For instance an additional mainmenu item must be inserted:
> the MDI 'Window' menu. That popup menu can't be handled by KPart because it is
> dynamically managed by the Qt-only MDI control. For example every MDI view user
> action changes the 'Window' menu because menu entries (the view entries) are
> changed.
> I see only a solution in that way: After KParts menu buildup I insert the 'Window'
> menu item manually by
>    menuBar()->insertItem(i18n("&Window"), m_MDIMainFrm->windowMenu(), -1, 7);
> Do you see another way?
> How about the dynamism in KParts GUI creation?

I think we should make KTMainWindow::menuBar() private ;-)

No, seriously, one should never have to call menuBar(), insertItem(),
etc. directly. There's always a better solution.

There are different ways how to make the oh-so-static GUI (static as it is
created from "static" xml) more dynamic. It mostly depends on how much of
the GUI you want to change at run-time.

The first way is to create a new KXMLGUIClient instance. The basic idea of
the xmlgui system is that you have one factory per mainwindow GUI.

A KXMLGUIClient instance represents a GUI fragment (could be even the
whole complete GUI) . Inserting a client "into" the factory creates the
GUI the client provides (via a DOM tree and actions) and merges it with
the already existing GUI (->created by previously added clients) . 

(note that all this is completely independend from kparts itself -> you
can use it without anything kparts related)

-> If you want to dynamically add/remove/change larger parts of a GUI
(i.e. a big menu (sub)tree or a bunch of toolbars/toolbar-buttons or
both) , then you might consider using a dedicated KXMLGUIClient instance
(usually you will want to inherit from that class) . Just add and remove
it from the KXMLGUIFactory instance.

The most obvious example where KXMLGUIClients are used is kparts itself
;-) . Every Part inherits from KXMLGUIClient.

Another example is the popupmenu in konqueror/kdesktop. It is composed
from KXMLGUIClient instances. An embedded part in konqueror which provides
a BrowserExtension implementation can emit the popupMenu signal with a
KXMLGUIClient reference attached as argument. Konqueror will then create
the "common" popupmenu and insert the provided client into the "popupmenu
gui" . This provides a maximum of flexibility for embedded parts which
want to provide the common konqueror popupmenu but still insert their own
part-specific actions or submenus, etc. into the popupmenu.

Using a KXMLGUIClient however is not very efficient (memory-usage
wise) for cases where you only want to add/remove a bunch of plain
actions. Here it's better to use so-called Actionlists.

The easiest way to describe the idea of actionlists is a simple example:

Imagine the following piece of xml:
...
<Menu>
 <Action name="blah" />
 ...
 <ActionList name="bar" />
 ...
 <Action name="foo" />
</Menu>

The point is that you can automatically expand the actionlist element
to a list of action tags, at run-time.

So the result could look like:

...
<Menu>
 <Action name="blah" />
 ...
 <Action name="someAction" />
 <Action name="anotherOne" />
 <Action name="evenThreeActions" />?
 ...
 <Action name="foo" />
</Menu>

Note that you can have multiple actionlist tags with the same name within
one xml document scope. They will all automatically get expanded (or
removed) .

This however is just an illustration. Internally this expansion is handled
completely different and without anyyhing xml related. However
illustrating it with the example of xml makes it easier to understand.

So the insertion (or deletion) of an actionlist is done at run-time via
the plugActionList/unplugActionList methods. Implementation wise you just
provide a QList of KAction objects.

An example where actionlists are used is the list of viewmode toolbar
buttons in Konqueror (i.e. the buttons which let you quickly switch
between iconview, treeview, etc. ) . These buttons are implemented as
actionlist (have a look at konqueror.rc and you'll see :)

Hope this helps a bit :) Feel free to bomb with questions/suggestions :)


Bye,
 Simon