Blame doc/html/widgetclasses.html

Packit 1e8aac
Packit 1e8aac
<html>
Packit 1e8aac
<head>
Packit 1e8aac
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
Packit 1e8aac
<title>Widget Adaptor Definitions: Glade User Interface Designer Reference Manual</title>
Packit 1e8aac
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
Packit 1e8aac
<link rel="home" href="index.html" title="Glade User Interface Designer Reference Manual">
Packit 1e8aac
<link rel="up" href="catalog.html" title="Part I. Adding your custom widgets">
Packit 1e8aac
<link rel="prev" href="catalogintro.html" title="Introducing the Glade Catalog">
Packit 1e8aac
<link rel="next" href="properties.html" title="Property Class Definitions">
Packit 1e8aac
<meta name="generator" content="GTK-Doc V1.28 (XML mode)">
Packit 1e8aac
<link rel="stylesheet" href="style.css" type="text/css">
Packit 1e8aac
</head>
Packit 1e8aac
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Home
Packit 1e8aac
Up
Packit 1e8aac
Prev
Packit 1e8aac
Next
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Widget Adaptor Definitions

Packit 1e8aac

Widget Classes —

Packit 1e8aac
Adding support for custom widgets 
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Forward

Packit 1e8aac

Packit 1e8aac
Widget support in Glade is provided by the GladeWidgetAdaptor object, each
Packit 1e8aac
`glade-widget-class' definition in the catalog will result in the creation
Packit 1e8aac
of an adaptor, which inherits the funcionality of the adaptor created for its
Packit 1e8aac
parent, or the closest adaptor available in the ancestry. Adaptor methods can
Packit 1e8aac
be overridden by functions in the plugin by specifying them in the catalog.
Packit 1e8aac
There is also a wealth of options you can use in the `glade-widget-class' without
Packit 1e8aac
writing code.
Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
A typical basic example of a widget class definition is as follows:
Packit 1e8aac
      

Packit 1e8aac
Packit 1e8aac
<glade-widget-class name="FooFrobnicator" generic-name="frobnicator" title="Frobnicator"/>
Packit 1e8aac

Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
Here is the complete example of the form of the `glade-widget-class' definition:
Packit 1e8aac
      

Packit 1e8aac
Packit 1e8aac
<glade-widget-class name="FooFrobnicator" generic-name="frobnicator" title="Frobnicator"/>
Packit 1e8aac
  <post-create-function>foo_frobnicator_plugin_post_create</post-create-function>
Packit 1e8aac
Packit 1e8aac
  ... widget class support functions go here
Packit 1e8aac
Packit 1e8aac
  <properties>
Packit 1e8aac
    <property id="frobnicated" default="False"/>
Packit 1e8aac
Packit 1e8aac
    ... property definitions go here
Packit 1e8aac
  </properties>
Packit 1e8aac
Packit 1e8aac
  <signals>
Packit 1e8aac
    <signal id="frobnicate" since="1.0"/>
Packit 1e8aac
Packit 1e8aac
    ... signal definitions go here
Packit 1e8aac
  </signals>
Packit 1e8aac
Packit 1e8aac
  <packing-properties>
Packit 1e8aac
    ... child packing property definitions go here
Packit 1e8aac
  </packing-properties>
Packit 1e8aac
Packit 1e8aac
  <actions>
Packit 1e8aac
    <action id="launch_editor" name="Edit Frob" stock="gtk-edit"/>
Packit 1e8aac
Packit 1e8aac
    ... context menu action definitions go here
Packit 1e8aac
  </actions>
Packit 1e8aac
Packit 1e8aac
  <packing-actions>
Packit 1e8aac
    ... context menu action definitions for child objects go here
Packit 1e8aac
  </packing-actions>
Packit 1e8aac
Packit 1e8aac
  <packing-defaults>
Packit 1e8aac
    <parent-class name="GtkVBox">
Packit 1e8aac
      <child-property id="expand" default="false"/>
Packit 1e8aac
    </parent-class>
Packit 1e8aac
Packit 1e8aac
    ... packing default definitions go here
Packit 1e8aac
  </packing-defaults>
Packit 1e8aac
</glade-widget-class>
Packit 1e8aac

Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Widget Class Properties

Packit 1e8aac

Packit 1e8aac
The following are all properies of the `glade-widget-class' tag
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

name

Packit 1e8aac

Packit 1e8aac
The class name of the widget; unless the 'get-type-function' property is present, 
Packit 1e8aac
this will essentially be used to instantiate the actual class by deriving 
Packit 1e8aac
'gtk_label_get_type' from 'GtkLabel' and searching for 'gtk_label_get_type' in the 
Packit 1e8aac
support library.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

since

Packit 1e8aac

Packit 1e8aac
A 'major.minor' formed version describing the version of the owning catalog in which this 
Packit 1e8aac
object class was introduced; example: since="1.0".
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

deprecated

Packit 1e8aac

Packit 1e8aac
A boolean property depicting that this widget is currently deprecated.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

builder-unsupported

Packit 1e8aac

Packit 1e8aac
A boolean property depicting that this widget is not supported by GtkBuilder.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

get-type-function

Packit 1e8aac

Packit 1e8aac
Used to explicitly specify the name of the function used to get the type of the widget.  
Packit 1e8aac
It is optional, but if it is not present, the 'name' property will be used to guess the
Packit 1e8aac
name of the function, a process that could lead to unexpected results.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

generic-name

Packit 1e8aac

Packit 1e8aac
Used to generate a default name for instances of the
Packit 1e8aac
widget in the UI editor. It is also used in conjunction with the 'icon-prefix'
Packit 1e8aac
to form an icon name for the widget.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

icon-name

Packit 1e8aac

Packit 1e8aac
Used to explicitly set an icon name for this widget.
Packit 1e8aac
These icon names are looked up in the current icon theme to retrieve an icon for
Packit 1e8aac
the widget.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

title

Packit 1e8aac

Packit 1e8aac
Used to display the name of the class in the palette and widget 
Packit 1e8aac
tree and will be translated before use in the interface.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

parent

Packit 1e8aac

Packit 1e8aac
Use this to specify the name of the parent your widget derives from, you
Packit 1e8aac
can use this option instead of loading a real widget type (this allows you
Packit 1e8aac
to fake derive and still add properties and run your catalog independantly
Packit 1e8aac
of any plugins or libraries).
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

toplevel

Packit 1e8aac

Packit 1e8aac
Used to know whether this widget class is toplevel or not
Packit 1e8aac
in Glade context. This property will be inherited from the adaptors parent.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

fixed

Packit 1e8aac

Packit 1e8aac
Used to mark a GladeWidgetClass for free form placement capacities
Packit 1e8aac
to be handled with a GladeFixed. This property will be inherited from the adaptors parent.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

use-placeholders

Packit 1e8aac

Packit 1e8aac
Used to inform the core about adaptors that implement
Packit 1e8aac
GtkContainer editing, and whether or not they use GladePlaceholder. This property will 
Packit 1e8aac
be inherited from the adaptors parent.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

default-width

Packit 1e8aac

Packit 1e8aac
The default width to load a GtkWindow derived widget in the GladeDesignView.
Packit 1e8aac
This property will be inherited from the adaptors parent.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

default-height

Packit 1e8aac

Packit 1e8aac
The default height to load a GtkWindow derived widget in the GladeDesignView.
Packit 1e8aac
This property will be inherited from the adaptors parent.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Adapter Methods

Packit 1e8aac

Packit 1e8aac
The following are all child tags of the `glade-widget-class' tag
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

constructor-function

Packit 1e8aac

Packit 1e8aac
Used to override the actual GObject constructor of the said GladeWidgetAdaptor
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

post-create-function

Packit 1e8aac

Packit 1e8aac
A GladePostCreateFunc support function that gets called whenever a widget of the said class is instantiated.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

deep-post-create-function

Packit 1e8aac

Packit 1e8aac
Same as `post-create-function' except in that you must always chain up
Packit 1e8aac
to the super class definition as a rule.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

get-property-function

Packit 1e8aac

Packit 1e8aac
A GladeGetPropertyFunc to get values of properties on an instance in the
Packit 1e8aac
runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

set-property-function

Packit 1e8aac

Packit 1e8aac
A GladeSetPropertyFunc to set values of properties on an instance in the
Packit 1e8aac
runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

verify-function

Packit 1e8aac

Packit 1e8aac
A GladeVerifyPropertyFunc to set values of properties on an instance in the
Packit 1e8aac
runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

add-child-function

Packit 1e8aac

Packit 1e8aac
A GladeAddChildFunc to add children to instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

remove-child-function

Packit 1e8aac

Packit 1e8aac
A GladeRemoveChildFunc to remove children from instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

replace-child-function

Packit 1e8aac

Packit 1e8aac
A GladeReplaceChildFunc to replace children inside instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

get-children-function

Packit 1e8aac

Packit 1e8aac
A GladeGetChildrenFunc to get a list of children inside instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

child-get-property-function

Packit 1e8aac

Packit 1e8aac
A GladeChildGetPropertyFunc to get packing properties from instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

child-set-property-function

Packit 1e8aac

Packit 1e8aac
A GladeChildSetPropertyFunc to set packing properties on instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

child-verify-function

Packit 1e8aac

Packit 1e8aac
A GladeChildVerifyPropertyFunc to verify packing properties on instances in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

get-internal-child-function

Packit 1e8aac

Packit 1e8aac
A GladeGetInternalFunc to retrieve an internal child of a composite object in the runtime.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

action-activate-function

Packit 1e8aac

Packit 1e8aac
A GladeActionActivateFunc to run a routine for a plugin defined GladeWidgetAction.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

child-action-activate-function

Packit 1e8aac

Packit 1e8aac
A GladeChildActionActivateFunc to run a routine for a plugin defined packing GladeWidgetAction.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

read-widget-function

Packit 1e8aac

Packit 1e8aac
A GladeReadWidgetFunc to load a widget from the xml.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

write-widget-function

Packit 1e8aac

Packit 1e8aac
A GladeWriteWidgetFunc to write a widget from the xml.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

read-child-function

Packit 1e8aac

Packit 1e8aac
A GladeReadWidgetFunc to read a child to the xml.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

write-child-function

Packit 1e8aac

Packit 1e8aac
A GladeWriteWidgetFunc to write a child to the xml.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

create-editor-property-function

Packit 1e8aac

Packit 1e8aac
A GladeCreateEPropFunc to create widgets to be used in Glade's property editor.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

string-from-value-function

Packit 1e8aac

Packit 1e8aac
A GladeStringFromValueFunc to create a string from a GValue, these strings must
Packit 1e8aac
be unique and comparable for undo/redo to work properly.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Action Definitions

Packit 1e8aac

Packit 1e8aac
Actions are added under the `actions' and `packing-actions' tags, actions can also
Packit 1e8aac
be nested so as to allow grouping in context menus, example:
Packit 1e8aac
      

Packit 1e8aac
Packit 1e8aac
...
Packit 1e8aac
Packit 1e8aac
<action id="manage_frobs" name="Manage Frobs">
Packit 1e8aac
  <action id="add_frob" name="Add" stock="gtk-add"/>
Packit 1e8aac
  <action id="remove_frob" name="Remove" stock="gtk-remove"/>
Packit 1e8aac
</action>
Packit 1e8aac
Packit 1e8aac
...
Packit 1e8aac

Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
Here are the meanings of the `action' tag's properties:
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

id

Packit 1e8aac

Packit 1e8aac
The string identifier for this action, the action_path argument to your GladeActionActivateFunc
Packit 1e8aac
will be a combination if this id and any parents, for the above example: 
Packit 1e8aac
"manage_frobs/add_frob".
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

name

Packit 1e8aac

Packit 1e8aac
A string to be displayed in the UI for this action.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

stock

Packit 1e8aac

Packit 1e8aac
An optional Gtk stock icon to represent this action.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

important

Packit 1e8aac

Packit 1e8aac
A boolean option to add emphasis to this action; currently actions marked as `important' 
Packit 1e8aac
are added to the toolbar.
Packit 1e8aac
          

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Packing Defaults

Packit 1e8aac

Packit 1e8aac
Default values can be specified for packing properties on your widget when added
Packit 1e8aac
to a said type of parent, as the example shows above; use the `parent-class' to 
Packit 1e8aac
specify what parent (or derivative of that parent) you are targetting and fill
Packit 1e8aac
in any `child-property' tags you need for that parent using `id' property to 
Packit 1e8aac
specify the property name and the `default' property for the value.
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Signals

Packit 1e8aac

Packit 1e8aac
The signal elements are currently only needed for versioning support, use
Packit 1e8aac
the `signal' child tag as described above and set signal `id' to be supported
Packit 1e8aac
since version `since'. Signals are initialized to be supported since the
Packit 1e8aac
introducing GladeWidgetAdaptor was supported.
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Icons

Packit 1e8aac

Packit 1e8aac
The Glade palette and other components use icons to represent the various widget classes. 
Packit 1e8aac
It is a good idea to provide icons for your widget classes, as this
Packit 1e8aac
enhances the user interface.
Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
Glade uses the GTK+ GtkIconTheme facility to provide icons for widget classes. Any icon
Packit 1e8aac
available in the current icon theme can be used as an icon for a widget class.
Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
By default, an icon name of the format "widget-CATALOG_NAME-GENERIC_NAME"
Packit 1e8aac
is assigned to every widget class. CATALOG_NAME is the value of catalog name attribute, 
Packit 1e8aac
and GENERIC_NAME is the value of an widget class's generic name attribute.
Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
To explicity set an icon name for a widget class, the "icon-name" attribute of the
Packit 1e8aac
"glade-widget-class" element can be specified. This will override the default icon 
Packit 1e8aac
name assigned to the widget class.
Packit 1e8aac
    

Packit 1e8aac

Packit 1e8aac
Icon files can be installed under any system icon theme folder.
Packit 1e8aac
    

Packit 1e8aac
Packit 1e8aac
Packit 1e8aac
Packit 1e8aac

Generated by GTK-Doc V1.28
Packit 1e8aac
</body>
Packit 1e8aac
</html>