class PanelApplet

The PanelApplet is a an object in the GNOME panel. It is a Gtk::Container, that can hold a single Gtk::Widget.

The Factory description

To create a PanelApplet, you have to provide a factory description. The discription is an XML document of the following format. It has to be stored under #{prefix}/lib/bonobo/servers/OAFIID:GNOME_ExampleApplet_Factory.server, where the ExampleApplet-part has to be the same as the OAFIID.

<oaf_info>
<oaf_server iid="OAFIID:GNOME_ExampleApplet_Factory"
  type="exe"
  location="/usr/bin/example_applet">
  <oaf_attribute name="repo_ids" type="stringv">
    <item value="IDL:Bonobo/GenericFactory:1.0"/>
    <item value="IDL:Bonobo/Unknown:1.0"/>
  </oaf_attribute>
  <oaf_attribute name="name" type="string" value="Example Applet Factory"/>
  <oaf_attribute name="description" type="string" value="Example Applet Factory"/>
</oaf_server>
<oaf_server iid="OAFIID:GNOME_ExampleApplet"
  type="factory" 
  location="OAFIID:GNOME_ExampleApplet_Factory">
  <oaf_attribute name="repo_ids" type="stringv">
    <item value="IDL:GNOME/Vertigo/PanelAppletShell:1.0"/>
    <item value="IDL:Bonobo/Control:1.0"/>
    <item value="IDL:Bonobo/Unknown:1.0"/>
  </oaf_attribute>
  <oaf_attribute name="name" type="string" value="Exmaple"/>
  <oaf_attribute name="description" type="string" value="This is an panel applet example"/>
  <oaf_attribute name="name-de" type="string" value="Beispiel"/>
  <oaf_attribute name="description-de" type="string" value="Dies ist ein panel applet Beispiel"/>
  <oaf_attribute name="panel:icon" type="string" value="exampleimage"/>
  <oaf_attribute name="panel:category" type="string" value="Accessories"/>
</oaf_server>
</oaf_info>

The parts in detail (only relevant parts are discribed):

<oaf_server iid="OAFIID:GNOME_ExampleApplet_Factory"
type="exe"
location="/usr/bin/example_applet">

• iid: a uniq name for the factory object, that is the same as the filename without the ".server".
• location: the path to the file, that will generate the content of the applet.

.

<oaf_attribute name="name" type="string" value="Example Applet Factory"/>
<oaf_attribute name="description" type="string" value="Example Applet Factory"/>

• name and description: it is common to use the applets name + Factory. AFAIK this values are unused.

.

<oaf_server iid="OAFIID:GNOME_ExampleApplet"
type="factory" 
location="OAFIID:GNOME_ExampleApplet_Factory">

• iid: a uniq name for the applet, that is the same as used for the factory object without the "_Factory".
• location: the factories iid from above.

.

<oaf_attribute name="name" type="string" value="Exmaple"/>
<oaf_attribute name="description" type="string" value="This is an panel applet example"/>

• name and decription: the name and a description of the applet. This will be shown in the dialog, where applets can be choosen for addition to the panel. To localize (translate) these entries, the ISO country code of the language has to be appended on the name and/or description elements, separated by a minus. The value then contains the translated name and description, like shown for German in the example.

.

<oaf_attribute name="panel:icon" type="string" value="exampleimage"/>

• panel:icon: the name of the icon without the filetype (i.e. .png), that shall be displayed in the applet chooser dialog. The icon has to be located in #{datadir}/icons/hicolor/*size*/apps/exampleimage.png. *size* are the different icon sizes. Because the size may depend on the used theme, it is secure to place scaled icons in all of the 16x16, 22x22, 24x24, 32x32 and 48x48 folders

FIXME: is this true, or is always a fixed size used?.

Applet initialization

The applets "binary" that in this example is stored under /usr/bin/example_applet has the following content.

require 'panelapplet2'

OAFIID = "OAFIID:GNOME_ExampleApplet_Factory"
oafiid = OAFIID

init = proc do |applet, iid|
  applet.add_preferences '/schemas/apps/example_applet/prefs'
  applet.set_flags PanelApplet::EXPAND_MINOR
  gui = MyApplet.new applet
  applet << gui
  applet.show_all
  true
end

PanelApplet.main oafiid, "ExampleApplet", "0.1", &init

The relevant parameters are:

OAFIID

• has to match factory description in the server file.

.

applet.add_preferences '/schemas/apps/example_applet/prefs'

• add a GConf path, that points to the applets preferences

.

gui = MyApplet.new applet

• here the applets content is generated. How that will look like, is on you.

.

applet << gui

• the applets content is packed into the applet container.

.

PanelApplet.main oafiid, "ExampleApplet", "0.1", &init

• Tis call glues it all together.

• Object
  • GLib::Instantiatable
    • GLib::Object
      • GLib::InitiallyUnowned
        • Gtk::Object
          • Gtk::Widget
            • Gtk::Container
              • Gtk::Bin
                • Gtk::EventBox
                  • PanelApplet

PanelApplet.new

Creates a new PanelApplet

You normally wouldn't use this method, as the PanelApplet will be created by the PanelApplet Factory.

• Returns : a new PanelApplet

PanelApplet.need_gnome?

Returns true if the GNOME desktop environment is needed to creat panel applets.

• Returns: whether the GNOME desktop environment is needed

background

Gets the panels background type and its background.

• Returns: an array with two values, with the current Background Type? at first. The second value comes after this rules:

PanelApplet::BackgroundType::NO_BACKGROUND => nil

PanelApplet::BackgroundType::COLOR_BACKGROUND => a Gdk::Color which contains the panels background color

PanelApplet::BackgroundType::PIXMAP_BACKGROUND => a Gdk::Pixmap with a copy of the area, the applet covers in the panel

size

Returns a size hint for the applet. From the Gtk+ docs this methode is mostly useless.

set_size_hints(size_hints, base_size)

TODO

orient

Gets the current orientation? of the applet.

• Returns: depending on the direction, the panel expands to one of the following values.

get_flags()

The Flags? associated with the applet are boolean flags which the panel may read in order to figure out how to handle the applet.

Returns: the requested flags

set_flags(flags)

Set the Flags? to the PanelApplet

• flags: the flags to set
• Returns: self

request_focus(time_stamp)

Sets the keyboard focus to the applet. This is needed if the applet shall contain a Gtk::Entry or a Gtk::ComboBoxEntry. This method has to be connected to the enter_notify_event of a GTk::EventBox that contains the entry or to the button_press_event of the Gtk::Entry or Gtk::ComboBoxEntry.child. With the first, the Entry gets the focus if the pointer enters the applet, with the second, the user has to click into the entry.

• time_stamp: the timestamp of the event (Gdk::EventButton#time or Gdk::EventCrossing#time)
• Returns: self

set_menu(xml, [[verb, proc], ...])

Sets the right click context menu of the panel.

• xml: is the XML description for the menu entries
• [[verb, proc], ...] are pairs of menu verbs an Proc objects
• Returns: self

The XML description consists of a startline

"<popup name=\"button3\">"

none or more menu items

"  <menuitem name=\"Item 1\" verb=\"about\" _label=\"About\" pixtype=\"stock\" pixname=\"gtk-about\"/>"

none or more separators

"  <separator/>"

and and endline

"</popup>"

in the menu item is

• name: an uniq name
• verb: an uniq name, that reffers to the first parameter of each verb <=> Proc object pair
• _label: the label to display in the menu
• pixtype: the type of the pixmap, that shall be displayed beside of the label
• pixname: the name of the pixmap

(fixme: what types are possible and how to reffer to non stock items?)

In the verb <=> Proc object pair is

• verb: a name, that refers to a menu item
• proc: a Proc object, that will be called if the menu item gets activated

So a menu with an about and a preferences entry can look like this:

xml = "<popup name=\"button3\">" +
"  <menuitem name=\"Item 1\" verb=\"about\" _label=\"About\"" +
"     pixtype=\"stock\" pixname=\"gtk-about\"/>" +
"  <menuitem name=\"Item 2\" verb=\"pref\" _label=\"Preferences\"" +
"     pixtype=\"stock\" pixname=\"gtk-properties\"/>" +
"</popup>\n"

@applet.set_menu xml, [['about', Proc.new{callback_about}],
                       ['pref',  Proc.new{callback_preferences}]]

add_preferences(schema_dir)

Associates each schema in schema_dir with a key in the applet's preferences directory.

• schemas: The GConf path where the applet's schemas are installed
• Returns: self

control

Gets the bonobo contol of the applet.

• Returns: the bonobo control

popup_component

Gets the Bonobo::UI::Componet, that is used for the popup menu.

• Returns: the Bonobo::UI::Componet

preferences_key

Returns the GConf path to the directory containing the applet's per-instance preference keys. Using this you may construct the full path for the applet's preference keys.

• Returns: a string with the GConf path

gconf_set_bool(key, value)

Sets a boolean value in the Applets GConf configuration

• key: the key of the value to set
• value: the boolean value to set
• Returns: self

gconf_set_int(key, value)

Sets an integer value in the Applets GConf configuration

• key: the key of the value to set
• value: the inter value to set
• Returns: self

gconf_set_float(key, value)

Sets a float value in the Applets GConf configuration

• key: the key of the value to set
• value: the float value to set
• Returns: self

gconf_set_string(key, value)

Sets a string in the Applets GConf configuration

• key: the key of the value to set
• value: the string value to set
• Returns: self

gconf_get_bool(key)

Gets a boolean value from the Applets GConf configuration. If the type of the requested value is not a boolean, an exception will be raised.

• key: the key of the value to get

Returns: the configuration value if the key is found, otherwise false

gconf_get_int(key)

Gets an integer value from the Applets GConf configuration. If the type of the requested value is not an integer, an exception will be raised.

• key: the key of the value to get

Returns: the configuration value if the key is found, otherwise 0

gconf_get_float(key)

Gets a float value from the Applets GConf configuration. If the type of the requested value is not a float, an exception will be raised.

• key: the key of the value to get

Returns: the configuration value if the key is found, otherwise 0.0

gconf_get_string(key)

Gets a string from the Applets GConf configuration. If the type of the requested value is not a string, an exception will be raised.

• key: the key of the value to get

Returns: the configuration value if the key is found, otherwise nil

BackgroundType

BackgroundType::NO_BACKGROUND

no background is set to the panel

BackgroundType::COLOR_BACKGROUND

the background of the panel is colored

BackgroundType::PIXMAP_BACKGROUND

the panel has a Gdk::Pixmap as background

Orientation

ORIENT_UP

ORIENT_DOWN

ORIENT_LEFT

ORIENT_RIGHT

Flags

FLAGS_NONE

No flags are to be associated with the applet.

EXPAND_MAJOR

The applet should expand horizontally on an horizontal panel and vertically on a vertical panel.

EXPAND_MINOR

The applet should expand vertically on an horizontal panel and horizontally on a vertical panel.

HAS_HANDLE

The panel should draw a grab handle on one side of the applet.

The PanelApplet signals are not bound yet

Gtk::StatusIcon

• 2009-06-04 Add factory description and Applet initialization Detlef
• 2009-05-26 Create this page. - Detlef