Next Previous Contents

3. Dynamic GUI system

3.1 Introduction

eboxy plugins can now query, modify and even create the GUI at runtime inside eboxy.

3.2 Adding widgets

To create a new widget at runtime, you can either create it from scratch, create one based on a template, or clone an existing widget. The createWidget or cloneWidget API functions are used to do this. When a new widget is created or cloned, it goes into a constructed widget "holding area". Set any properties you wish to set before using it, and then add the widget to a page, using the AddWidget method of the page (supplying the name of the widget to add). You can add it to the current page or to any other page, including pages you create at runtime (more on this below).

3.3 Adding pages

You can also create new pages at runtime. Use the createPage API function to do this. To actually display the page, use the changePage API function to change to it.

3.4 Tidying up

The deletePage and deleteWidget API functions should be used to remove pages and widgets from memory when you no longer need them. Note that deletePage may be used to delete pages that were loaded from an XML file, but deleteWidget may only be used on widgets that you create (the same applies to the RemoveWidget method of page objects). Also, using deletePage on a page that contains widgets you have created does not absolve you of the responsibility of deleting the created widgets - these remain in the holding area, and you must run deleteWidget on each of them to clean them up - so you should keep track of them. You should not use deleteWidget to delete a widget that is still on a page - use the page's RemoveWidget method to remove the widget first, then delete it.

Note that unlike custom objects, widgets are not owned by plugins - they will remain if your plugin is unloaded before eboxy quits. If you do not want them to be persistent, you should explicitly remove them. However, at this present time, if you change to a different XML file, the created pages will be cleared out - this is considered to be a bug and will be fixed in subsequent versions of eboxy.

3.5 Enumerating objects

eboxy now provides ways to enumerate various elements of the GUI at runtime. Enumeration is provided in the form of a "get count, get item at index" interface.

Enumerating object properties, methods and events

To enumerate properties on an object, first retrieve the value of the propertycount property, and then call the getproperty method in a loop, passing the index (from 0 to count-1) on each iteration. In this way you can retrieve the name of each property on the object. You can do likewise for methods and events by using methodcount/getmethod and eventcount/getevent respectively. These can be used on most types of eboxy object accessible through the plugin API. There is a demonstration of doing this in the testbench plugin.

Enumerating widgets

Page objects have a property widgetcount and a method getwidget which can be used to enumerate the widgets on a particular page in the manner described previously.

Enumerating pages

To enumerate available pages, use the pagecount property and getpage method of the system object.


Next Previous Contents