Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboPropertyControl

## Name

BonoboPropertyControl -- an interface for exposing property editors as controls

## Synopsis

    struct      BonoboPropertyControl;
    typedef     BonoboPropertyControlClass;
    BonoboControl* (*BonoboPropertyControlGetControlFn)
                                                (BonoboPropertyControl *control,
                                                 int page_number,
                                                 void *closure);
    BonoboPropertyControl* bonobo_property_control_new
                                                (BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 void *closure);
    BonoboPropertyControl* bonobo_property_control_new_full
                                                (BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 BonoboEventSource *event_source,
                                                 void *closure);
    BonoboPropertyControl* bonobo_property_control_construct
                                                (BonoboPropertyControl *property_control,
                                                 BonoboEventSource *event_source,
                                                 BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 void *closure);
    void        bonobo_property_control_changed (BonoboPropertyControl *property_control,
                                                 CORBA_Environment *opt_ev);
    BonoboEventSource* bonobo_property_control_get_event_source
                                                (BonoboPropertyControl *property_control);
    #define     BONOBO_PROPERTY_CONTROL_CHANGED

## Object Hierarchy

      GtkObject
       +----BonoboObject
             +----BonoboXObject
                   +----BonoboPropertyControl

## Signal Prototypes

    "action"    void        user_function      (BonoboPropertyControl *bonobopropertycontrol,
                                                gint arg1,
                                                gint arg2,
                                                gpointer user_data);

## Description

This interface is designed to allow things that offer GUI customization a nice way to provide both multi and single page customization controls. Each page is exposed as a BonoboControl, and contain any arbitary widgets. Each control in a multi-page configuration should expose a string property named "bonobo:title" which contains a translated label suitable for using in a tabbed dialog.

An interface is also provided for applying each page's contents, and requesting help for that page. The interface also provides a BonoboEventSource to which a BonoboListener can be connected. Changes can be listened for which will arrive on the event with name BONOBO_PROPERTY_CONTROL_CHANGED.

A new single page BonoboPropertyControl interface can be created thus:

Example 1. A simple property control interface

    static void
    stop_start_cb (GtkToggleButton *button, GtkClock *clock)
    {
    	if (button->active)
    		gtk_clock_start (clock);
    	else
    		gtk_clock_stop (clock);
    }

    static BonoboControl *
    get_page_fn (BonoboPropertyControl *control,
                 int                    page_number,
                 void                  *closure)
    {
    	GtkClock  *clock = closure;
    	GtkWidget *widget = gtk_checkbutton_new_with_label (
    		"Clock is running");

    	gtk_widget_show (widget);

    	gtk_signal_connect (GTK_OBJECT (widget), "toggled",
    			    GTK_SIGNAL_FUNC (stop_start_cb), clock);

    	return bonobo_control_new (widget);
    }

    BonoboObject *
    add_property_interface (BonoboObject *aggregate, GtkClock *clock)
    {
    	BonoboPropertyControl *pc;

    	pc = bonobo_property_control_new (get_page_fn, 1, clock);

    	bonobo_object_add_interface (aggregate_object, BONOBO_OBJET (pc));

    	return aggregate_object;
    }

## Details

### struct BonoboPropertyControl

    struct BonoboPropertyControl;

### BonoboPropertyControlClass

    typedef struct {
    	BonoboXObjectClass parent_class;

    	POA_Bonobo_PropertyControl__epv epv;

    	void (* action) (BonoboPropertyControl *property_control,
    			 Bonobo_PropertyControl_Action action);
    } BonoboPropertyControlClass;

### BonoboPropertyControlGetControlFn ()

    BonoboControl* (*BonoboPropertyControlGetControlFn)
                                                (BonoboPropertyControl *control,
                                                 int page_number,
                                                 void *closure);

`control` : |
`page_number` : |
`closure` : |
Returns : |

### bonobo_property_control_new ()

    BonoboPropertyControl* bonobo_property_control_new
                                                (BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 void *closure);

Creates a BonoboPropertyControl object.

`get_fn` : | The function to be called when the getControl method is called.
`num_pages` : | The number of pages this property control has.
`closure` : | The data to be passed into the `get_fn` routine
Returns : | A pointer to a newly created BonoboPropertyControl object.

### bonobo_property_control_new_full ()

    BonoboPropertyControl* bonobo_property_control_new_full
                                                (BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 BonoboEventSource *event_source,
                                                 void *closure);

Creates a BonoboPropertyControl object.

`get_fn` : | The function to be called when the getControl method is called.
`num_pages` : | The number of pages this property control has.
`event_source` : | The event source to use to emit events on.
`closure` : | The data to be passed into the `get_fn` routine.
Returns : | A pointer to a newly created BonoboPropertyControl object.

### bonobo_property_control_construct ()

    BonoboPropertyControl* bonobo_property_control_construct
                                                (BonoboPropertyControl *property_control,
                                                 BonoboEventSource *event_source,
                                                 BonoboPropertyControlGetControlFn get_fn,
                                                 int num_pages,
                                                 void *closure);

Initialises the BonoboPropertyControl object.

`property_control` : | A BonoboPropertyControl object.
`event_source` : | A BonoboEventSource object that will be aggregated onto the property control.
`get_fn` : | Creation routine.
`num_pages` : |
`closure` : | Data passed to closure routine.
Returns : | The newly constructed BonoboPropertyControl.

### bonobo_property_control_changed ()

    void        bonobo_property_control_changed (BonoboPropertyControl *property_control,
                                                 CORBA_Environment *opt_ev);

Tells the server that a value in the property control has been changed, and that it should indicate this somehow.

`property_control` : | The BonoboPropertyControl that has changed.
`opt_ev` : | An optional CORBA_Environment for exception handling.

### bonobo_property_control_get_event_source ()

    BonoboEventSource* bonobo_property_control_get_event_source
                                                (BonoboPropertyControl *property_control);

Returns the BonoboEventSource that `property_control` uses.

`property_control` : | The BonoboPropertyControl.
Returns : | A BonoboEventSource.

### BONOBO_PROPERTY_CONTROL_CHANGED

    #define BONOBO_PROPERTY_CONTROL_CHANGED "Bonobo::PropertyControl_changed"

## Signals

### The "action" signal

    void        user_function                  (BonoboPropertyControl *bonobopropertycontrol,
                                                gint arg1,
                                                gint arg2,
                                                gpointer user_data);

`bonobopropertycontrol` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

BonoboProperty, BonoboPropertyBag, BonoboControl

<<< Previous Page | Home | Up | Next Page >>>
BonoboControlFrame | Bonobo Compound Documents