[gnome-panel] Revert "remove old libpanel-applet documentation"
- From: Alberts Muktupāvels <muktupavels src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-panel] Revert "remove old libpanel-applet documentation"
- Date: Sun, 8 Oct 2017 17:25:02 +0000 (UTC)
commit 6e30f6ebef8af808113d4b2a39b41d957f4776d0
Author: Alberts Muktupāvels <alberts muktupavels gmail com>
Date: Tue Mar 21 17:20:43 2017 +0200
Revert "remove old libpanel-applet documentation"
This reverts commit cdd562fb48ce26336e1fe932194bbd29e2ea69bd.
Makefile.am | 1 +
configure.ac | 4 +
doc/Makefile.am | 7 +
doc/gnome-panel-action-protocol.txt | 26 +
doc/panel-keynav.txt | 84 ++
doc/panel-session-handling.txt | 250 ++++
doc/pre-2.4-thoughts.txt | 246 ++++
doc/reference/Makefile.am | 7 +
doc/reference/libpanel-applet/Makefile.am | 97 ++
doc/reference/libpanel-applet/add_to_panel.png | Bin 0 -> 50415 bytes
.../libpanel-applet/libpanel-applet-docs.xml | 1408 ++++++++++++++++++++
.../libpanel-applet/libpanel-applet-sections.txt | 43 +
doc/release-steps.txt | 150 +++
13 files changed, 2323 insertions(+), 0 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 52b7f7c..0dadd52 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -5,6 +5,7 @@ SUBDIRS = \
modules \
gnome-panel \
libpanel-applet \
+ doc \
docs \
help \
data \
diff --git a/configure.ac b/configure.ac
index f2931ad..cffb7af 100644
--- a/configure.ac
+++ b/configure.ac
@@ -268,6 +268,10 @@ AC_CONFIG_FILES([
libpanel-applet/Makefile
libpanel-applet/libpanel-applet.pc
+ doc/Makefile
+ doc/reference/Makefile
+ doc/reference/libpanel-applet/Makefile
+
docs/Makefile
docs/reference/Makefile
docs/reference/libgnome-panel/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..a37f6cf
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,7 @@
+SUBDIRS = reference
+
+EXTRA_DIST= \
+ panel-session-handling.txt \
+ panel-keynav.txt
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/gnome-panel-action-protocol.txt b/doc/gnome-panel-action-protocol.txt
new file mode 100644
index 0000000..0267981
--- /dev/null
+++ b/doc/gnome-panel-action-protocol.txt
@@ -0,0 +1,26 @@
+_GNOME_PANEL_ACTION Protocol
+
+ The _GNOME_PANEL_ACTION is a simple mechanism whereby an
+ application window invoke one of a number of simple
+ actions which will be handled by the GNOME panel. This
+ protocol is intended to be used by window managers who
+ provide keybindings for these actions.
+
+ To invoke an action the application sends the following
+ ClientMessage to the root window of the screen on which
+ the keybinding was activated:
+
+ type = ClientMessage
+ window = the root window
+ message_type = _GNOME_PANEL_ACTION
+ format = 32
+ data.l[0] = action
+ data.l[1] = timestamp
+
+ Possible action atoms are:
+
+ _GNOME_PANEL_ACTION_MAIN_MENU, ATOM
+ _GNOME_PANEL_ACTION_RUN_DIALOG, ATOM
+ _GNOME_PANEL_ACTION_KILL_DIALOG, ATOM
+
+ Unsupported actions are ignored by the panel.
diff --git a/doc/panel-keynav.txt b/doc/panel-keynav.txt
new file mode 100644
index 0000000..d1014ab
--- /dev/null
+++ b/doc/panel-keynav.txt
@@ -0,0 +1,84 @@
+This note describes areas where implementation of keynav for panels was
+difficult.
+
+- PanelWidget and objects on the panel such as launchers and applets need to
+be focusable
+
+Both the PanelWidget and objects on the panel need to be focusable in order
+to invoke the context menu using only the keyboard. In the normal course of
+things, GTK+ does not support a widget and its children be focusable.
+
+Instead of requiring the PanelWidget be focusable we have introduced a key
+binding Ctrl+F10 which pops up the panel's context menu. So a PanelWidget
+is focusable only when it does not have any children. There is, therefore,
+no need for the key binding Ctrl+Tab to move the focus to the PanelWidget from
+an applet or a launcher.
+
+The function panel_widget_real_focus is PanelWidget's default signal
+handler for focus signal. This function is called when either PanelWidget
+or a child has focus and Tab or arrow keys are used to move focus. If the
+PanelWidget has focus and the PanelWidget has children the GTK_CAN_FOCUS flag
+is unset so that a child can receive focus.
+
+- An applet with a tooltip receives focus
+
+If an applet has a tooltip, the applet will receive focus so that the tooltip
+can be displayed, even if the applet contains focusable widgets. The
+focusable widgets in the applet can be traversed using the arrow keys.
+
+
+- Tab should move focus from within an applet to the next object on the panel
+
+This is implemented by defining an action signal "move_focus_out_of_applet"
+on PanelApplet and binding Tab and Shift+Tab to this action.
+
+When focus is in an applet the event is passed to the focus widget then its
+children until a toplevel is reached unless the event is handled. This is
+done in gtk_window_key_press_event(). The original implemementation for
+"move_focus_out_of_applet" had the action signal defined on PanelAppletFrame
+but as a GtkSocket always reports a key press event as being handled when
+the GtkPlug is in a different process, the event has not passed to the
+PanelAppletFrame.
+
+The implementation for "moving_focus_out_of_applet" sets a flag
+moving_focus_out so that the function panel_applet_focus() which is
+PanelApplet's default signal handler for focus signal will not attempt to
+move the focus within the applet if this flag is set.
+
+
+- Implementing key bindings
+
+If focus is in an applet which is in another process, the GtkSocket will
+report the key stroke as having been handled. This means that key bindings
+will not be activated. The workaround for this is to handle those key
+strokes in panel_event() a signal handler for the event signal in panel.c.
+However, we only want to handle some keybindings, for example we do not want
+to handle Shift+F10, which displays the context menu, and Ctrl+F1, which
+displays the tooltip, but we do want to handle Ctrl+F10 which displays the
+panel's context menu.
+
+
+- Focus indication
+
+We need a mechanism that will make visible which panel has focus. We also
+need to do this without impacting current behaviour.
+
+We set the state of a PanelWidget to GTK_STATE_SELECTED whan focus is in a
+PanelWidget. We provide a default panel rc file gnome-panelrc, which is
+installed in $(datadir). This rc file sets the default default color for
+SELECTED for any widget which is a descended from a PanelWidget or
+PanelApplet to be the same as the NORMAL colour.
+
+If there is a requirement to make panel focus indication visible, the
+following lines added to ~/.gtkrc-2.0 will make a selected panel prelight
+color.
+
+style "prelight-selected"
+{
+ fg[SELECTED] = { 0, 0, 0 }
+ bg[SELECTED] = { 0xea60, 0xea60, 0xea60 }
+}
+
+widget_class "*PanelWidget*" style "prelight-selected"
+widget_class "*PanelApplet*" style "prelight-selected"
+
diff --git a/doc/panel-session-handling.txt b/doc/panel-session-handling.txt
new file mode 100644
index 0000000..71c2efc
--- /dev/null
+++ b/doc/panel-session-handling.txt
@@ -0,0 +1,250 @@
+Panel session/configuration handling
+====================================
+
+(Please read the session-management docs in porting-docs before
+reading this)
+
+Panel global configuration
+--------------------------
+All the panel configuration options that are not per panel are stored
+in GConf in the /apps/panel/global folder. There is a schema for it,
+and sysadms can override the defaults by changing the defaults in the
+default database.
+
+It will look like this
+
+ /apps/panel/global/run_dialog_key
+ /apps/panel/global/auto_hide_speed
+ /apps/panel/global/auto_hide_delay
+
+etc.
+
+Panel Profiles
+--------------
+
+All the per-panel setup is stored in named profiles. Initially the
+"Default" profile is created for you, and if you never create a new
+profile everything seems to the user just like profiles don't exist.
+The profiles contain all the per-panel settings and the per-applet
+settings.
+
+Each profile stores it's configuration in GConf in a separate prefix,
+like this:
+ /apps/panel/profile/Default/
+ /apps/panel/profile/Work/
+ /apps/panel/profile/Home/
+ /apps/panel/profile/Laptop/
+
+When a new profile is created it's content is copied from a default
+profile choosen depending on the screen size. The defaults are stored
+in /apps/panel/default-profiles, like this:
+
+ /apps/panel/default-profiles/small/
+ /apps/panel/default-profiles/medium/
+ /apps/panel/default-profiles/large/
+
+These are delivered in a serialized fashion in gnome-core, and the (to
+be written by hp) gconf deserialization app is used to install
+them at make install/package install time. Then the sysadmin can
+change these as he sees fit. I can imagine a "make current profile be
+default" button somewhere.
+
+[ This is a area where opinions differ.
+
+ alex:
+ The active profile can typically be changed by the user any time
+ using a popdown menu or suchlike. (Just imagine selecting a new
+ profile and all the panels will go swooosh and pop up in their
+ new places with different applets and stuff.)
+
+ _vicious_:
+ The name of the active profile is always the same as the current
+ gsm named session.
+]
+
+Per-Session Data
+----------------
+
+NOTE: This section only applies to alex version aboce. In _vicious_
+version, there would be no real per-session data, just the session name.
+
+The only per-session data saved by the panel is which profile it
+uses. In general per-session data should only be trivial things that
+the user won't be mad when(if?) he loses. According to hp's
+session-management docs in the porting-docs:
+
+ This can all be kind of a pain, so apps are encouraged to
+ save all their state as part of the command they pass to the
+ session manager, and avoid saving persistent files. That is, it's
+ easier and more robust to have a command line option
+ --with-window-count=3 than it is to store the window count in GConf under
+ /apps/terminal/sessions/4543-3252345-6745/window_count
+ and provide a discard command to clear that key.
+
+It seems unnecessary to store the panel per session data in GConf, so
+we would just store the command line saved to the session manager as
+"--profile=Laptop" (replace laptop by name of active profile). This
+way we won't have problems cleaning up GConf either.
+
+Per-Panel configuration
+-----------------------
+
+The panel profile data would looks something like this:
+
+ /apps/panel/profile/Laptop/panels/12345/panel_type
+ /some_per-panel_setting
+ /which_applet_ids_are_in_this_panel
+ /33214/ ...
+ /apps/panel/profile/Laptop/applets/43234/applet_type (oaf id?)
+ /some_applet_setting
+ /prefs/ <- This is where the applet itself
+ stores it's per-instance prefs.
+ /56378/ ...
+
+This means that the panel profile configuration data is a list
+of panels with unique ids, that has per panel settings, and a list of
+applets with unique ids (applets may move between panels, and need to
+keep their prefs, so they are not in the panel subfolder).
+
+Each applet folder also have a "prefs" folder
+(e.g. /apps/panel/profile/Laptop/applets/43234/prefs/) which is used by the
+applet to store it's per instance data.
+
+Applet Prefs
+------------
+
+An applet has two sorts of preferences, per-instance and global. The
+per-instace perferences are options that may be different for each
+instance of the applet (such as number of rows in the pager), while
+the global preferences are preferences that are shared by all running
+applets of that type (and even non-running ones in different
+profiles). Examples of global preferences may be tooltip timeouts, or
+in deskguide the number of windows in a class before grouping starts.
+
+It is important that the preferences ui for the applet separates the
+global and the per-instance settings in some way, so users do not get
+totally confused about what is applied to all instances and what is not.
+
+Global applet preferences are managed entierly by the applet, and is
+normally stored in GConf in a key such as:
+
+ /apps/applet/deskguide/grouping_limit
+
+Global settings have normal GConf behaviour, and the applet should
+install a schema for them.
+
+Per-instance preferences are private to the applet. You should write
+schemas for them for good measure, but currently GConf doesn't handle
+dynamic keys well, so they will not be installed. In the future this
+will be fixed though. The keys are private anyway, so not having
+schemas does not matter that much, since other apps should not modify
+them (and can't find them since they are dynamic and prefixed with
+strange id's).
+
+When the panel instantiates an applet (first time or not) it will give
+the applet a GConf prefix (see above) for it to read and write it's
+per-instance configuration from. Since there is no way currently to
+have schemas for these dynamic prefixes there won't be any default
+values for the applet settings. Thus we have to hardcode the settings
+in the applet.
+
+So the way to read prefs changes slightly. You have to try reading,
+and if there is no data in gconf, use the default value. The way to
+use this is to call gconf_client_get(), which return NULL if the value
+is unset and has no default (this means it will automagically work
+whenever we implement dynamic prefix schemas).
+
+We should probably wrap the gconf calls in some utility functions like
+this:
+
+gint
+applet_gconf_get_int_with_default (SomeAppletType *applet,
+ const gchar* key,
+ gint default,
+ GError** err)
+{
+ GError* error = NULL;
+ GConfValue* val;
+ GConfClient *client = panel_gconf_get_client ();
+ gchar *full_key;
+
+ g_return_val_if_fail(err == NULL || *err == NULL, 0);
+
+ full_key = applet_get_full_key (applet, key);
+ val = get(client, full_key, TRUE, NULL, NULL, &error);
+ g_free (full_key);
+
+ if (val != NULL)
+ {
+ gint retval = def;
+
+ g_assert(error == NULL);
+
+ if (check_type(key, val, GCONF_VALUE_INT, &error))
+ retval = gconf_value_get_int(val);
+ else
+ handle_error(client, error, err);
+
+ gconf_value_free(val);
+
+ return retval;
+ }
+ else
+ return default;
+}
+
+And the applet would use this like this
+
+#define TOOLTIP_TIMEOUT_DEFAULT 100 /* msec */
+
+ timeout = applet_gconf_get_int_with_default ("tooltip_timeout", TOOLTIP_TIMEOUT_DEFAULT, NULL);
+
+It is important that we have actual defines for the defaults, so as to
+not repeat the problems we had previously, with different defaults in
+different places.
+
+Session Manager interaction
+---------------------------
+
+[NOTE: Only applies to alex version, _vicious_ one doesn't even need this ]
+
+The panels responds to the SaveYourself request, but does not need to
+propagate this request to the applets, since the applet settings are
+stored per-instance-in-a-profile, and not in a session. This makes
+things robust (won't lose applet setup), and easier to understand for
+the user.
+
+The only thing the panel needs to do on SaveSetup is to pass the
+command line containing the active profile "--profile=Laptop" to the
+session manager. There are no GConf cleanup needed, or no session id
+thrown about at all.
+
+
+Full example GConf tree
+-----------------------
+/apps/applet/deskguide/grouping_limit
+ ...
+/apps/applet/clock/format
+ ...
+/apps/panel/global/run_dialog_key
+/apps/panel/global/auto_hide_speed
+/apps/panel/global/auto_hide_delay
+ ...
+/apps/panel/profile/Default/panels/12345/type
+ ...
+/apps/panel/profile/Default/panels/54543/type
+ ...
+/apps/panel/profile/Default/applets/62568/oaf_iid
+/apps/panel/profile/Default/applets/62568/prefs/ ...
+ ...
+/apps/panel/profile/Default/applets/43355/oaf_iid
+/apps/panel/profile/Default/applets/43355/prefs/ ...
+ ...
+/apps/panel/profile/Coding/ ...
+/apps/panel/profile/Gaming/ ..
+/apps/panel/default-profiles/small/ (panels and applets)
+/apps/panel/default-profiles/medium/ (panels and applets)
+/apps/panel/default-profiles/large/ (panels and applets)
+/schemas/apps/applet/deskguide/
+/schemas/apps/applet/clock/
+/schemas/apps/panel/global/
diff --git a/doc/pre-2.4-thoughts.txt b/doc/pre-2.4-thoughts.txt
new file mode 100644
index 0000000..ff441a6
--- /dev/null
+++ b/doc/pre-2.4-thoughts.txt
@@ -0,0 +1,246 @@
+
+* Things which need discussion
+
+ + New toplevel behaviour
+ + Toplevel keybindings
+ + Configuration
+ + GConf usage
+
+New toplevel behaviour
+======================
+
+ There are some mildly controversial changes in the panel
+behaviour with the new toplevel widget.
+
+ 1) Autohiding hides into the corner of the screen. This change
+ was recommended by the usability team based on the fact the
+ unhiding the panel isn't any harder - you just throw the
+ mouse into the corner of the screen - but it makes
+ operations near the edge of the screen a lot less error
+ prone - previously you had to be careful not to go near the
+ hidden panel.
+
+ 2) GTK+ stock arrows on the hide buttons. I went for these
+ instead of using the previous pixmaps because it makes
+ theming easier and the default stock arrows are actually a
+ lot clearer, IMHO.
+
+ 3) Grab handle on floating panels with no hide buttons.
+ Discussed before - previously there was no way to access
+ the panel context menu on a floating panel. I'd imagine
+ some people will cry "ugly", but I haven't seen a better
+ suggestion yet.
+
+ 4) Hiding a floating panel using the hide buttons makes the
+ panel hide to the edge of the screen rather than just
+ resizing into a button. Originally the reason I did this
+ was temporary - currently the panel animations only allow
+ moving the panel, not resizing it - but I've come to prefer
+ the behaviour.
+
+ 5) Floating panels now snap to the edge, corner and center (at
+ the edge) of the screen. I think this makes sense, but
+ maybe the snap region at 20 pixels is too big.
+
+ 6) You can rotate a floating panel with the mouse by holding
+ down Ctrl when moving it with the mouse.
+
+ 7) You can resize the panel by clicking on the edge and
+ dragging. Note, that you can change the width (height for
+ vertical panels) of floating panels. The idea is that
+ floating panels are "packed". I think this is a sensible
+ concept.
+
+
+ I think that's about it. I'd encourage people to check out the
+"new-toplevel" branch (don't install it, just run it from the source
+dir - it doesn't recognise your preferences) and experiment with the
+behaviour before commenting.
+
+Panel toplevel keybindings
+==========================
+
+ The new toplevel widget currently binds some of metacity's
+window keybindings to similar functions on the panel.
+
+ + activate_window_menu: popup the panel context menu. Same
+ thing as Ctrl-F10.
+
+ + toggle_maximized: toggle between expanded/un-expanded.
+
+ + maximize: expand the panel.
+ + unmaximize: un-expand the panel.
+
+ + toggle_shaded: toggle the panel between hidden/un-hidden. If
+ you have autohide enabled this does autohiding type
+ behaviour, otherwise its does hiding in a similar way to
+ doing it with the hide buttons.
+
+ + begin_move:
+ + begin_resize: move/resize the panel in similar ways to the
+ way you can move/resize windows using the keyboard with
+ metacity.
+
+ So there's a few questions about this:
+
+ 1) Does it make sense to overload the window keybindings with
+ similar functions on panels. It may lead to user confusion,
+ but I think it will just make learning the panel bindings
+ easier and also free us of the burden of coming up with new
+ key sequences for these operations.
+
+ 2) Are the activate_window_menu and toggle_shaded bindings
+ similar enough to popping up the context menu and hiding
+ the panel similar enough to warrant the overloading. I
+ think the others definetly make sense.
+
+ 3) Are there any other operations which would benefit from
+ keybindings like this. They don't neccessarily need to have
+ equivalent ones in metacity.
+
+ 4) We're tying ourselves closely here to metacity. Maybe we
+ should only do this if metacity is running (this is what
+ the keybindings dialog does).
+
+ To test this out with the "new-toplevel" branch you need the
+attached patch for metacity.
+
+GConf Usage
+===========
+
+ We made a litany of mistakes when we did the porting from
+gnome-config to GConf for 2.0:
+
+ 1) We use schemas for the default setup in a very dubious way.
+ As a side effect it is extremely awkward to change the
+ default panel setup.
+ 2) We came up with the idea of panel "profiles" but never
+ exposed it in the interface and didn't add the ability to
+ switch between profiles.
+ 3) Panel doesn't respond to GConf notifications
+ 4) Using huge long internal identifiers for for panels and
+ applets which makes it very hard to grok the panel's
+ gconf tree.
+ 5) Various little mistakes like storing a bitfield as an ints
+ etc.
+ 6) Not all changes are written to gconf immediately, there's
+ still some weird remenants that I don't fully understand of
+ saving configuration on receipt of SaveYourself and various
+ global timeouts for saving all the panel configuration.
+ 7) Saving the configuration to GConf on startup even though
+ nothing has changed.
+
+ So, clearly 3, 4, 5, 6, and 7 are pretty obvious things to
+fix. Some of them will take a fair bit of work to fix, but there's no
+arguments on what the behaviour should be.
+
+========
+
+ (1) is pretty tough to figure out what should be done.
+Currently the panel does the following:
+
+ + Installs a set of "schemas" into /schemas/apps/panel/default-profiles
+ which really is just the default configuration tree. e.g. we
+ install schemas like:
+
+/schemas/apps/panel/profiles/default/panels/000001/size
+/schemas/apps/panel/profiles/default/panels/000002/size
+
+ when clearly we should have a single schema:
+
+/schemas/apps/panel/panels/size
+
+ which is then applied to the keys:
+
+/apps/panel/profiles/default/panels/000001/size
+/apps/panel/profiles/default/panels/000002/size
+
+ The default specified in the schema should just be the
+ default size when you create a new panel and so we need a
+ seperate place to get the information that "the default
+ panel setup should have a 32 pixel wide panel on the top and
+ a 24 pixel wide panel on the bottom".
+
+ The most sensible solution to this is that the default panel
+ setup should get installed into the defaults database. This
+ could be done in a number of ways:
+
+ * Use a gconftool script which would write the default setup
+ to the defaults database. It would look something like:
+
+export GCONF_CONFIG_SOURCE='xml:readwrite:/usr/etc/gconf/gconf.xml.defaults'
+gconftool-2 --direct
+ -s /apps/panel/profiles/default/panels/00001/size -t int 32
+gconftool-2 --direct
+ -s /apps/panel/profiles/default/panels/00002/size -t int 24
+
+ * Come up with a homegrown file format for describing a the
+ default panel setup and write a simple program for parsing
+ it and installing it into the defaults database. It might
+ look something like:
+
+<default_profile>
+ <toplevel id="top_menu_panel">
+ <name>Top Menu Panel</name>
+ <orientation>top</orientation>
+ <size>24</size>
+ <auto_hide>false</auto_hide>
+ <enable_buttons>false</enable_buttons>
+ <background type="plain"/>
+
+ <applet iid="">
+ </applet>
+
+ <object type="">
+ </object>
+ </toplevel>
+</default_profile>
+
+ * Come up with a new GConf file format which
+ --makefile-install-rule would handle just like the .schemas
+ file. This file format would effectively be a gconf script
+ e.g
+
+<gconfvaluesfile>
+ <valueslist>
+
+ <value type="int" key="/apps/panel/profiles/default/panels/0001/size">24</value>
+ <value type="int" key="/apps/panel/profiles/default/panels/0002/size">32</value>
+
+ </valueslist>
+</gconfvaluesfile>
+
+
+ Because of profiles and needing to be able to use the default
+setup on newly available screens, the default setup needs to always be
+available, so we would actually need to be able to install these
+defaults in somewhere like
+
+ /apps/panel/default-setup
+
+ so that we can copy it everytime we start a new profile or
+find that we've logged into a machine with a screen with no panels
+configured for it.
+
+=========
+
+ (2) is something else which needs to be decided upon. The
+original idea behind them was for session management. You could have a
+different panel setups for different purposes. I've just read over
+gnome-panel/doc/panel-session-handling.txt and reminded myself of what
+this was all about.
+
+ Alex wanted something similar to gnome-terminal AFAIK, you
+could switch between profiles at runtime, create new profiles etc. If
+you save your session, the current profile you are using is saved so
+you use this profile every time you log in to that session.
+
+ George wanted to have the current profile to be decided by the
+current session name - you basically have a profile for each session.
+
+ Thinking about it, I prefer George's approach (even though I'd
+completely forgotten about it).
+
+ Alternatively, we could forget the whole idea of session
+management with the panel. All your configuration is global and is the
+same for all sessions.
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
new file mode 100644
index 0000000..3420906
--- /dev/null
+++ b/doc/reference/Makefile.am
@@ -0,0 +1,7 @@
+NULL =
+
+SUBDIRS = \
+ libpanel-applet \
+ $(NULL)
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/reference/libpanel-applet/Makefile.am b/doc/reference/libpanel-applet/Makefile.am
new file mode 100644
index 0000000..222d252
--- /dev/null
+++ b/doc/reference/libpanel-applet/Makefile.am
@@ -0,0 +1,97 @@
+NULL =
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE = libpanel-applet
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION =
+
+# The top-level XML file.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
+DOC_SOURCE_DIR = $(top_srcdir)/libpanel-applet
+
+# Extra options to pass to gtkdoc-scangobj. Normally not needed.
+SCANGOBJ_OPTIONS =
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS = --rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS = --xml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS =
+
+# Extra options to supply to gtkdoc-fixref. Normally not needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS =
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB = $(top_srcdir)/libpanel-applet/*.h
+CFILE_GLOB = $(top_srcdir)/libpanel-applet/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES =
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES = \
+ panel-applet-bindings.h \
+ panel-applet-enums.h \
+ panel-applet-factory.h \
+ panel-applet-private.h \
+ $(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES = \
+ add_to_panel.png \
+ $(NULL)
+
+# Extra files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.xml building.xml changes-2.0.xml
+content_files =
+
+# Files where gtk-doc abbrevations (#GtkWidget) are expanded
+# e.g. expand_content_files=running.xml
+expand_content_files =
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS = \
+ -I$(top_srcdir)/libpanel-applet \
+ -I$(top_builddir)/libpanel-applet \
+ $(PANEL_CFLAGS) \
+ $(NULL)
+
+GTKDOC_LIBS = \
+ $(top_builddir)/libpanel-applet/libpanel-applet.la \
+ $(PANEL_LIBS) \
+ $(NULL)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
+
+-include $(top_srcdir)/git.mk
diff --git a/doc/reference/libpanel-applet/add_to_panel.png b/doc/reference/libpanel-applet/add_to_panel.png
new file mode 100644
index 0000000..0d6f05f
Binary files /dev/null and b/doc/reference/libpanel-applet/add_to_panel.png differ
diff --git a/doc/reference/libpanel-applet/libpanel-applet-docs.xml
b/doc/reference/libpanel-applet/libpanel-applet-docs.xml
new file mode 100644
index 0000000..9dea9d7
--- /dev/null
+++ b/doc/reference/libpanel-applet/libpanel-applet-docs.xml
@@ -0,0 +1,1408 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>
+<book id="index">
+
+ <bookinfo>
+ <title>Panel Applet Reference Manual</title>
+ <releaseinfo>
+ This document is for the Panel Applet library, version &package_version;.
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location"
url="https://developer.gnome.org/libpanel-applet/unstable/";>https://developer.gnome.org/libpanel-applet/unstable/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+
+ <part id="overview">
+ <title>Panel Applet Library Overview</title>
+ <partintro>
+ <para>
+ The Panel Applet Library is used in the GNOME Flashback desktop to write applets that can be added
to GNOME
+ Panel. GNOME Panel is the main user interface used in the GNOME Flashback desktop environment,
through which
+ users interact with their computer and open applications.
+ </para>
+
+ <para>
+ Applets are small applications that are embedded in the GNOME Panel. They can be used to give quick
access
+ to some features, or to display the state of something specific. Most features in GNOME Panel such
as the clock,
+ the application menu, the calendar and many others are written with this Panel Applet Library.
Applets are added
+ through the "Add to Panel" dialog which can be opened from the "Add to Panel..." option on the
context menu of
+ a GNOME Panel.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="add_to_panel.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ The Panel Applet Library is what should be used to write applets as it handles all the communication
with
+ the GNOME panel. It hides all of the embedding process of the applet behind a
+ <link linkend="PanelApplet"><type>PanelApplet</type></link> widget. It also provides
+ <link linkend="reference"><type>PanelApplet API</type></link> to properly integrate the applet in the
+ panel.
+ </para>
+
+ <note>
+ <simpara>
+ The Panel Applet Library was original part of the default GNOME desktop but was deprecated with
GNOME 3,
+ when GNOME Shell was released. Nowadays development continues as part of the GNOME Flashback
project. The
+ default desktop of GNOME now uses GNOME Shell, which uses a different system for extension, so an
applet
+ written with the Panel Applet Library will not be usable in the default GNOME that users may use.
+ </simpara>
+ </note>
+ </partintro>
+
+ </part>
+
+ <part id="getting-started">
+ <title>Getting Started with the Panel Applet library</title>
+
+ <chapter id="getting-started.intro">
+ <title>Introduction</title>
+
+ <para>
+ While applets are rather simple to write, they are not the most easy form of interaction to users for
two reasons:
+ <itemizedlist>
+ <listitem>
+ It is not intuitive how to add or remove applets for many users, so users may not know about
your applet,
+ or may not know how to add it to the GNOME Panel.
+ </listitem>
+ <listitem>
+ The restriction in size of applets can limit their interface, so you should only use applets for
simple
+ tasks such as displaying information, or for controlling other applications and programs.
+ </listitem>
+ </itemizedlist>
+ Therefore, before writing an applet, think hard whether this is the form of interaction that
+ is best for the feature you want to provide.
+ </para>
+
+ </chapter>
+
+ <chapter id="getting-started.concepts">
+ <title>Concepts</title>
+
+ <para>
+ In order to write an applet it is important to understand the relationships between GNOME Panel and
your
+ applets. For example, how are applets registered to the GNOME Panel? How does the GNOME Panel
instantiate an
+ applet?
+ </para>
+ <para>
+ On a typical desktop there can be multiple GNOME Panels and each GNOME Panel can have several
instances of
+ your applet. These different instances are created by an <emphasis>applet factory</emphasis> which
must be
+ registered to the GNOME Panel. Additionally, in order to identify your applet and instantiate the
correct
+ applet, each applet is identified by an <emphasis>applet type</emphasis>.
+ </para>
+
+ <sect1>
+ <title>Applet Registration</title>
+
+ <para>
+ To make your applets and the applet factory known to GNOME Panel - so that it can show your
+ applet in the list of applets of the "Add to Panel" dialog - and to add applets to the panel,
you
+ must create a Panel Applet File.
+ <link linkend="getting-started.install.panel-applet">Panel Applet files</link> are introduced
in more
+ detail later in this document. However it is important for applet authors to understand the
relationship
+ between <emphasis>the panel applet file</emphasis>, <emphasis>the applet factory</emphasis>,
and the
+ <emphasis>applet type</emphasis>. Therefore this section contains a short example of a Panel
Applet file.
+ </para>
+
+ <sect2>
+ <title>Panel Applet Files</title>
+ <para>
+ <link linkend="getting-started.install.panel-applet">Panel Applet files</link> are
+ <constant>ini</constant>-file formatted files that contain the necessary information
about your
+ factory and your applet types. The following example listing shows a simple Panel Applet
file.
+ </para>
+ <informalexample>
+ <programlisting>
+ [Applet Factory]
+ Id=HelloWorldFactory
+ Name=Hello World Applet Factory
+ Description=Factory for our example applets
+
+ [HelloWorldApplet]
+ Name=Hello World
+ Description=The Hello World example applet
+ Icon=hello-world-icon
+ </programlisting>
+ </informalexample>
+ </sect2>
+
+ <sect2 id="getting-started.concepts.applet-types">
+ <title>Applet Types</title>
+
+ <para>
+ The applet type is the identifier representing a type of applets to the panel. It is a
simple string,
+ like <constant>HelloWorldApplet</constant> and is unique per
+ <link linkend="getting-started.concepts.applet-factory">applet factory</link>.
+ </para>
+
+ <note>
+ <simpara>
+ In the example listing above the applet type can be found in the second section title
+ (e.g. <constant>[HelloWorldApplet]</constant>, but without the square brackets).
+ </simpara>
+ </note>
+ </sect2>
+
+ <sect2 id="getting-started.concepts.applet-factory">
+ <title>Applet Factory</title>
+
+ <para>
+ The applet factory is an implementation detail that is mostly hidden by the Panel Applet
Library,
+ but it still appears in a few places such as:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link> macro, which is used
to build
+ out process applets. It gets the factory id passed as its first parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> macro, which is used
to build in
+ process applets. It gets the factory id passed as its first parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A Panel Applet file, which is used to register applet types and the applet factory
to the
+ GNOME Panel. It must contain the same applet factory id as used in the above two
macros.
+ </para>
+ <warning>
+ <simpara>By default applets are out-process, if you have used the
+ <function>PANEL_APPLET_IN_PROCESS_FACTORY</function>, then you must add:
+ <constant>InProces=true</constant> to the <constant>[Applet
Factory]</constant>
+ section.
+ </simpara>
+ </warning>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The applet factory is the object that will create a new applet instance when the panel
requests a
+ new applet to be created. It is identified with a simple string id, for example
+ <constant>HelloWorldFactory</constant>.
+ </para>
+
+ <note>
+ <simpara>
+ In the example listing above the applet factory id can be found in the
+ <constant>ID</constant>-field of the <constant>[Applet Factory]</constant> section.
+ </simpara>
+ </note>
+
+ <para>
+ The requests the applet factory will receive from the GNOME Panel specify which type of
applet should be created.
+ This is what makes it possible to have more than one applet type in one applet binary. In
most cases, however, the
+ applet factory will be specific to only one applet type.
+ </para>
+
+ <para>
+ There is only one applet factory per applet binary, and it is always running before any
applet instance is
+ created by the applet binary. The applet factory is created via one of these two macros:
+ <itemizedlist>
+ <listitem>
+ <para><link
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link></para>
+ </listitem>, or
+ <listitem>
+ <para><link
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link></para>
+ </listitem>.
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="getting-started.concepts.applet-instances">
+ <title>Applet Instances</title>
+ <para>
+ There is no restriction as to how many instances of one applet type can be created. The user
might
+ choose to add more than one <constant>HelloWorldApplet</constant> applets to his panels. This
can
+ have some implications on the design used to write applets. The most important implication is
that
+ it is generally wrong to have global variables to keep a state specific to an applet instance.
+
+ <warning>
+ <simpara>
+ Using global variables in an applet can cause problems when the applet is instantiated
+ several times.
+ </simpara>
+ </warning>
+ </para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="getting-started.example">
+ <title>Hello World Example</title>
+
+ <para>
+ In this section we will write a simple example applet. This simple applet will have no functionality
and
+ only displays a label with "Hello World" on the panel. For this simple applet only following three
parts
+ are needed:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
+ </link>: this creates an <link linkend="getting-started.concepts.applet-factory">applet
factory</link> named
+ <constant>HelloWorldFactory</constant>, and each time our applet is added to a GNOME Panel,
this applet
+ factory will create an applet instance, and calls
<function>hello_world_factory_callback()</function>
+ with a <link linkend="PanelApplet"><type>PanelApplet</type></link> object already created.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <function>hello_world_factory_callback()</function>: this checks if the request to create an
applet
+ instance is for an <link linkend="getting-started.concepts.applet-types">applet type</link>
supported
+ by our <link linkend="getting-started.concepts.applet-factory">applet factory</link>. Here we
can see
+ that we only support the <constant>HelloWorldApplet</constant> applet type. This function
returns
+ <constant>TRUE</constant> on success and <constant>FALSE</constant> on failures.
+
+ <note>
+ <simpara>If you return <constant>FALSE</constant> here, GNOME Panel will show a dialog and
+ notify the user that the applet loading failed.</simpara>
+ </note>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <function>hello_world_applet_start()</function>: this is where we actually setup the
+ <link linkend="PanelApplet"><type>PanelApplet</type></link> widget for the work the applet
should do.
+ This can include adding widgets to the applet, connecting to signals, loading settings via
GSettings,
+ etc.
+
+ <note>
+ <simpara>
+ The PanelApplet is a subclass of <link linkend="GtkBin"><type>GtkBin</type></link>
+ container, to add more than one widget to it you will need to use another GtkContainer
+ implementation such as <link linkend="GtkBox"><type>GtkBox</type></link> or
+ <link linkend="GtkGrid"><type>GtkGrid</type></link>.
+ </simpara>
+ </note>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ An example is worth a million words, so here is the code for our <emphasis>Hello World</emphasis>
applet.
+ </para>
+
+ <example id="getting-started.example.simple">
+ <title>Hello World applet</title>
+ <programlisting language="c">
+#include <gtk/gtk.h>
+#include <panel-applet.h>
+
+static void
+hello_world_applet_start (PanelApplet *applet)
+{
+ GtkWidget *label;
+
+ label = gtk_label_new ("Hello World");
+ gtk_container_add (GTK_CONTAINER (applet), label);
+ gtk_widget_show_all (GTK_WIDGET (applet));
+}
+
+static gboolean
+hello_world_factory_callback (PanelApplet *applet,
+ const gchar *iid,
+ gpointer data)
+{
+ if (g_strcmp0 (iid, "HelloWorldApplet") != 0)
+ return FALSE;
+
+ hello_world_applet_start (applet);
+
+ return TRUE;
+}
+
+PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+ PANEL_TYPE_APPLET,
+ hello_world_factory_callback,
+ NULL)
+ </programlisting>
+ </example>
+
+ <para>
+ While the previous example is simple, it can be useful to directly subclass the
+ <link linkend="PanelApplet"><type>PanelApplet</type></link> type. This makes it easy to have a
per-applet
+ instance private structure, among other benefits. Most of the code below is related to the GObject
system
+ and needed to subclass the Panel Applet. The only noteworthy difference is that the
+ <constant>PANEL_APPLET_OUT_PROCESS_FACTORY</constant> macro now takes our subclassed type (e.g.
<constant>HELLO_WORLD_TYPE_APPLET</constant>)
+ as its second parameter, instead of <constant>PANEL_TYPE_APPLET</constant>.
+ </para>
+
+ <example id="getting-started.example.subclass">
+ <title>Hello World applet, with a PanelApplet subclass</title>
+ <programlisting language="c">
+#include <gtk/gtk.h>
+#include <panel-applet.h>
+
+#define HELLO_WORLD_TYPE_APPLET (hello_world_applet_get_type ())
+
+typedef struct _HelloWorldApplet HelloWorldApplet;
+typedef struct _HelloWorldAppletClass HelloWorldAppletClass;
+typedef struct _HelloWorldAppletPrivate HelloWorldAppletPrivate;
+
+struct _HelloWorldApplet {
+ PanelApplet parent_object;
+
+ /*< private >*/
+ HelloWorldAppletPrivate *priv;
+};
+
+struct _HelloWorldAppletClass {
+ PanelAppletClass parent_class;
+};
+
+struct _HelloWorldAppletPrivate
+{
+ GtkWidget *label;
+};
+
+static GType hello_world_applet_get_type (void) G_GNUC_CONST;
+
+G_DEFINE_TYPE (HelloWorldApplet, hello_world_applet, PANEL_TYPE_APPLET);
+
+static void
+hello_world_applet_init (HelloWorldApplet *applet)
+{
+ applet->priv = G_TYPE_INSTANCE_GET_PRIVATE (applet, HELLO_WORLD_TYPE_APPLET,
+ HelloWorldAppletPrivate);
+
+ applet->priv->label = gtk_label_new ("Hello World");
+ gtk_container_add (GTK_CONTAINER (applet), applet->priv->label);
+ gtk_widget_show (applet->priv->label);
+}
+
+static void
+hello_world_applet_class_init (HelloWorldAppletClass *klass)
+{
+ g_type_class_add_private (class, sizeof (HelloWorldAppletPrivate));
+}
+
+static
+hello_world_applet_start (HelloWorldApplet *applet)
+{
+ gtk_widget_show (GTK_WIDGET (applet));
+}
+
+static gboolean
+hello_world_factory_callback (HelloWorldApplet *applet,
+ const gchar *iid,
+ gpointer data)
+{
+ if (g_strcmp0 (iid, "HelloWorldApplet") != 0)
+ return FALSE;
+
+ hello_world_applet_start (applet);
+
+ return TRUE;
+}
+
+PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+ HELLO_WORLD_TYPE_APPLET,
+ hello_world_factory_callback,
+ NULL)
+ </programlisting>
+ </example>
+
+ </chapter>
+
+ <chapter id="getting-started.context-menu">
+ <title>Using a Context Menu</title>
+
+ <para>
+ The Panel Applet library uses <type>GAction</type> to define menu items appearing in the context menu
of the
+ applet. This chapter provides some guidelines to applet developers and explains how to setup the
context menu.
+ </para>
+
+ <sect1 id="getting-started.context-menu.content">
+ <title>Guidelines for Context Menu</title>
+
+ <para>
+ To help guarantee consistency in the interaction with applets, there are some guidelines that are
+ recommended to follow:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Do not make the context menu too long: if you have more than five or six menu items, then it might
be worth
+ investing efforts on rethinking what is important in the menu.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For the menu item that will enable the user to configure the applet, use "Preferences" for the label,
+ and try to avoid "Configure", "Configuration", "Settings", etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Avoid putting a "Help" menu item. The user will usually explicitly add the applet, so it is expected
that he knows what the applet is about.
+ Putting a "Help" menu item in the context menu is therefore too prominent. It might make sense to
add a "Help" button in the Preferences dialog, though.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you agree, avoid putting a "About" menu item. To the user, applets are not different applications
but elements of one global application, the panel. Of course, this means that credits
+ for working on the applet are not visible to the user.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id="getting-started.context-menu.setup">
+ <title>Setting Up the Menu</title>
+
+ <para>
+ The only part of dealing with a context menu that is specific to applets is how to setup the context
menu. Once it is setup, this is really just a matter of using <type>GtkAction</type>.
+ </para>
+
+ <para>
+ To setup the context menu of the applet, the <link
linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link>
function should be used, with a path to a <link linkend="getting-started.context-menu.xml-file">menu XML
file</link> and a <type>GtkActionGroup</type> object containing all actions that are used in the menu XML
file. The example below shows how to achieve this:
+ </para>
+
+ <example>
+ <title>Hello World applet, with a context menu</title>
+ <programlisting language="c">
+#include <glib/gi18n.h>
+#include <gtk/gtk.h>
+#include <panel-applet.h>
+
+/* This would usually be defined in config.h */
+#define GETTEXT_PACKAGE "hello-world"
+/* This would usually be defined in Makefile.am */
+#define HELLO_WORLD_UI_DIR "/usr/share/hello-world"
+
+static void hello_world_applet_prefs (GtkAction *action,
+ PanelApplet *applet);
+static void hello_world_applet_say (GtkAction *action,
+ PanelApplet *applet);
+
+static const GtkActionEntry hello_world_menu_actions [] = {
+ { "HelloWorldPrefs", GTK_STOCK_HELP, N_("_Preferences"),
+ NULL, NULL,
+ G_CALLBACK (hello_world_applet_prefs) },
+ { "HelloWorldSay", GTK_STOCK_ABOUT, N_("_Say Hello"),
+ NULL, NULL,
+ G_CALLBACK (hello_world_applet_say) }
+};
+
+static void
+hello_world_applet_prefs (GtkAction *action,
+ PanelApplet *applet)
+{
+ GtkWidget *dialog;
+ dialog = gtk_message_dialog_new (NULL, 0,
+ GTK_MESSAGE_INFO, GTK_BUTTONS_CLOSE,
+ "Preferences");
+ g_signal_connect (dialog, "response",
+ G_CALLBACK (gtk_widget_destroy), NULL);
+ gtk_widget_show (dialog);
+}
+
+static void
+hello_world_applet_say (GtkAction *action,
+ PanelApplet *applet)
+{
+ GtkWidget *dialog;
+ dialog = gtk_message_dialog_new (NULL, 0,
+ GTK_MESSAGE_INFO, GTK_BUTTONS_CLOSE,
+ "Hello World!");
+ g_signal_connect (dialog, "response",
+ G_CALLBACK (gtk_widget_destroy), NULL);
+ gtk_widget_show (dialog);
+}
+
+static gboolean
+hello_world_applet_start (PanelApplet *applet)
+{
+ GtkWidget *label;
+ GtkActionGroup *action_group;
+ gchar *ui_path;
+
+ label = gtk_label_new ("Hello World");
+ gtk_container_add (GTK_CONTAINER (applet), label);
+
+ action_group = gtk_action_group_new ("Hello World Applet Actions");
+ gtk_action_group_set_translation_domain (action_group, GETTEXT_PACKAGE);
+ gtk_action_group_add_actions (action_group,
+ hello_world_menu_actions,
+ G_N_ELEMENTS (hello_world_menu_actions),
+ applet);
+
+ ui_path = g_build_filename (HELLO_WORLD_UI_DIR, "hello-world-menu.xml", NULL);
+ panel_applet_setup_menu_from_file (applet, ui_path, action_group);
+
+ g_free (ui_path);
+ g_object_unref (action_group);
+
+ gtk_widget_show_all (GTK_WIDGET (applet));
+
+ return TRUE;
+}
+
+static gboolean
+hello_world_factory_callback (PanelApplet *applet,
+ const gchar *iid,
+ gpointer data)
+{
+ gboolean retval = FALSE;
+
+ if (g_strcmp0 (iid, "HelloWorldApplet") == 0)
+ retval = hello_world_applet_start (applet);
+
+ return retval;
+}
+
+PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+ PANEL_TYPE_APPLET,
+ hello_world_factory_callback,
+ NULL)
+ </programlisting>
+ </example>
+
+ <para>
+ Here are the changes compared to the <link linkend="getting-started.example.simple">simple
example</link> with no context menu:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ We define a list of <type>GtkActionEntry</type> entries:
<constant>hello_world_menu_actions</constant>. This will be used later on to build <type>GtkAction</type>
objects, with their label and callback. We obviously implement the callbacks.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ We change <function>hello_world_applet_start()</function> to define a <type>GtkActionGroup</type>
object, to which we add, with <function>gtk_action_group_add_actions()</function>, <type>GtkAction</type>
objects based on the <type>GtkActionEntry</type> entries. Note that the the last argument to
<function>gtk_action_group_add_actions()</function> will be passed as user data to the callbacks.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ We also change <function>hello_world_applet_start()</function> to add this
<type>GtkActionGroup</type> object to the context menu of the applet, by calling <link
linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link>.
This function takes as argument a path to the <link linkend="getting-started.context-menu.xml-file">menu XML
file</link> that will define how to display the <type>GtkAction</type> objects in the context menu.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect2 id="getting-started.context-menu.xml-file">
+ <title>Menu XML File</title>
+
+ <para>
+ The file that is used to setup menu with the <link
linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link>
function is a <type>GtkUIManager</type> UI definition file, without the top-level
<constant><ui></constant> tag. It must only contain menuitem entries and separators. For example:
+ </para>
+
+ <informalexample>
+ <programlisting>
+<menuitem name="Hello World Prefs" action="HelloWorldPrefs" />
+<separator/>
+<menuitem name="Hello World Say" action="HelloWorldSay" />
+ </programlisting>
+ </informalexample>
+
+ <para>
+ Alternatively, the <link
linkend="panel-applet-setup-menu"><function>panel_applet_setup_menu()</function></link> function can be used
with a string containing directly the XML.
+ </para>
+
+ </sect2>
+
+ </chapter>
+
+ <chapter id="getting-started.settings">
+ <title>Settings</title>
+
+ <para>
+ There are two main design patterns to store settings for an applet:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Global settings: those are settings that should be shared among all instances of the same applets.
+ For instance, the preferred unit for temperature is something that the user will want to set only one.
+ The way to store those settings is in no way specific to the Panel Applet library, as it should work
+ like in any other application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Per-applet instance settings: those are settings that might be different depending on the instance
+ of an applet. For instance, an applet whose goal is to display a picture should make it possible for
+ the user to choose a different picture for each instance of the applet. The Panel Applet library
+ provides API to help with this.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ There is actually a third case, which is rather rare, though: per-screen settings.
+ It might be that some applets control some per-screen settings, like the layout of the workspaces.
+ There is currently no API to help with this as it is a very specific case that you will probably
+ never have to deal with for a usual applet.
+ </para>
+
+ <sect1 id="getting-started.settings.per-instance">
+ <title>Per Instance Settings</title>
+ <para>
+ In order to store per instance settings for an applet it is recommended to use GSettings. The
+ Panel Applet Library privides a function named <function>panel_applet_settings_new()</function>
+ for this purpose. You need to provide a GSettings schema file for your applet and the Panel
+ Applet library will setup the GSettings object for you.
+ </para>
+
+ TODO: describe settings-oriented API in more detail and give an example for per instance settings.
+
+ </sect1>
+ </chapter>
+
+ <chapter id="getting-started.install">
+ <title>Applet Registration, Installation and Build System</title>
+
+ <para>
+ Simply installing the applet binary will obviously not be enough. The applet also needs to be
registered to the
+ panel. In order to do this you need to provide a Panel Applet File. Panel Applet files are ini-style
text
+ files with an extension named <constant>.panel-applet</constant>.
+ </para>
+
+ <warning>
+ <simpara>
+ If you are creating an out-process applet, then you also need to provide a D-Bus service file
+ to automatically start the binary when the panel wants to create an applet.
+ </simpara>
+ </warning>
+
+ <para>
+ This chapter explains the syntax of <constant>.panel-applet</constant> files and gives the
necessary
+ information to setup the build system in order to install all the required parts of the applet on
the system.
+ For the build system part it is assumed that GNU Autotools (e.g. autoconf and automake) are used.
+ </para>
+
+ <sect1 id="getting-started.install.panel-applet">
+ <title>Panel Applet File Syntax</title>
+
+ <para>
+ The <filename>.panel-applet</filename> file is a key file about the applet binary, describing the
+ <link linkend="getting-started.concepts.applet-factory">applet factory</link> of the binary and the
+ <link linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
+ </para>
+
+ <sect2>
+ <title>Panel Applet File Example</title>
+ <informalexample>
+ <programlisting>
+ [Applet Factory]
+ Id=HelloWorldFactory
+ Name=Hello World Applet Factory
+ Description=Factory for the our example applets
+
+ [HelloWorldApplet]
+ Name=Hello World
+ Description=Factory for the Hello World example applet
+ Icon=hello-world-icon
+ </programlisting>
+ </informalexample>
+ </sect2>
+
+ <sect2>
+ <title>File Format and well known Fields</title>
+ <para>
+ The file must contain a <constant>Applet Factory</constant> group with the following keys:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <constant>Id</constant> (string): the identifier of the applet factory. This must be the same name
that will be used as the first parameter to <link
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>
or <link
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>InProcess</constant> (boolean, optional): whether the applet should be <link
linkend="getting-started.in-out-process">in-process or out-of-process</link>. By default, the applet is
out-of-process.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>Location</constant> (string): the path to the applet binary. Only mandatory if
<constant>InProcess</constant> is <constant>true</constant>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>Name</constant> (localized string, optional): the name of the applet factory. For
example: <constant>Hello World Factory</constant>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>Description</constant> (localized string, optional): the description of the applet
factory. For example: <constant>Factory for the Hello World applet example</constant>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ For each applet type, it must also contain a group named with the applet type identifier. Such a
group must have the following keys:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <constant>Name</constant> (localized string): the name of the applet type. For example:
<constant>Hello World</constant>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>Description</constant> (localized string, optional): the description of the applet type.
For example: <constant>Hello World applet example</constant>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <constant>Icon</constant> (string, optional): the icon name of the applet type. For example:
<constant>hello-world-icon</constant>. It can also be the path to an icon, but this not recommended.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Installation</title>
+ <para>
+ The <filename>.panel-applet</filename> file must be installed in a specific directory to be
discoverable by the panel. The exact path of this directory can be queried with
<constant>pkg-config</constant>:
+
+ <informalexample>
+ <programlisting>
+ pkg-config --variable=libpanel_applet_dir libpanel-applet
+ </programlisting>
+ </informalexample>
+
+ The path depends on how GNOME Panel was compiled and installed so it could be different depending
on which
+ Linux distribution is used. Therefore never hard-code the path in your build system but use he
above
+ command instead.
+
+ Please see the <link linkend="getting-started.install.build-system">Build System</link> section
for more
+ information on how install a Panel Applet file with autotools.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="getting-started.in-out-process">
+ <title>Out-of-Process vs In-Process</title>
+
+ <para>
+ Applets can either live in their own process ("out-of-process") or in the panel process
("in-process").
+ The decision to choose one or the other is done at build time, with the macro that you use to
define the applet
+ factory:
+ <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
+ </link>
+ is used for out-of-process applets while
+ <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function>
+ </link> is used for in-process applets. Obviously, only one of those two macros can be used.
If both
+ types should be supported, then each macro must be placed between preprocessor conditions and
switched on
+ through a configure option. For example:
+
+ <informalexample>
+ <programlisting>
+ #ifdef MY_APPLET_OUT_PROCESS_ENABLED
+ PANEL_APPLET_OUT_PROCESS_FACTORY (...)
+ #else
+ PANEL_APPLET_IN_PROCESS_FACTORY (...)
+ #endif
+ </programlisting>
+ </informalexample>
+
+ </para>
+
+ <para>
+ For most practical matters, from the applet perspective, the two options are the same.
+ In-process applets do offer a slightly better performance when the applet is loaded, but this
should not have
+ much effect on the user experience. However, an in-process applet can potentially affect the
whole behavior of
+ the panel, especially in case of crashes or memory corruptions: a crash in an in-process
applet will crash the
+ whole panel. It is therefore recommended to use out-of-process applets.
+ </para>
+
+ <para>
+ The communication between the panel and the applet factory is done over D-Bus. When creating
an applet,
+ the panel will send a message to the D-Bus service of the applet factory. If the D-Bus
service is not
+ running yet, it must be started automatically. We use D-Bus activation for this, which
requires install a
+ standard D-Bus service file. This is only needed for, because in-process applets do no need
to have their
+ binary autostarted for obvious reasons.
+ </para>
+
+ <note>
+ <simpara>
+ Please refer to the
+ <ulink
url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services";>
+ D-Bus documentation</ulink> for more information about D-Bus service files.
+ </simpara>
+ </note>
+
+ <para>
+ Here is an example for a D-Bus Service file. It should be named
<constant>org.gnome.panel.applet.HelloWorldFactory.service.in</constant>
+ </para>
+ <informalexample>
+ <programlisting>
+ [D-BUS Service]
+ Name=org.gnome.panel.applet.HelloWorldFactory
+ Exec=@LOCATION@
+ </programlisting>
+ </informalexample>
+ <para>
+ Additionally you should adjust the build system to replace <constant>@LOCATION@</constant> by
the install location of the applet binary. The file itself must be installed into
+ <constant>$(datadir)/dbus-1/services/</constant>.
+ </para>
+
+ <para>
+ The next section contains an explanation how to setup the Makefile in order to install the
service file
+ to the correct location on the system.
+ </para>
+ </sect1>
+
+
+
+ <sect1 id="getting-started.install.build-system">
+ <title>Build system</title>
+
+ <sect2>
+ <title>Configure</title>
+
+ <para>
+ In <constant>configure.ac</constant> a variable should be defined that contains the
location
+ where the .panel-applet files are installed.
+
+ You can fetch this directory during <constant>configure</constant> with the following
code:
+ </para>
+
+ <informalexample>
+ <programlisting>
+ LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
+ AC_SUBST(LIBPANEL_APPLET_DIR)
+ </programlisting>
+ </informalexample>
+
+ </sect2>
+
+ <sect2>
+ <title>Makefiles</title>
+
+ A typical Makefile for that is used to build and install an applet contains the following
declarations:
+ <itemizedlist>
+ <listitem>
+ <para>A rule to install the <constant>.panel-applet</constant> file.</para>
+ </listitem>
+ <listitem>
+ <para>A rule to install the D-Bus service file if the applet is an out process
applet.</para>
+ </listitem>
+ <listitem>
+ <para>The <constant>.panel-applet</constant> file and the D-Bus
<constant>.service</constant> file
+ are added to EXTRA_DIST and CLEANFILES.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>Installing the Panel Applet File</title>
+ <informalexample>
+ <programlisting language="bash">
+ appletdir = $(LIBPANEL_APPLET_DIR)
+ applet_in_files = org.gnome.HelloWorld.panel-applet.in
+ applet_DATA = $(applet_in_files:.panel-applet.in=.panel-applet)
+
+ $(applet_in_files): $(applet_in_files).in Makefile
+ $(AM_V_GEN)sed \
+ -e "s|\@LIBEXECDIR\@|$(libexecdir)|" \
+ -e "s|\@VERSION\@|$(PACKAGE_VERSION)|" \
+ $< > $@
+
+ %.panel-applet: %.panel-applet.in \
+ $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ; \
+ $(INTLTOOL_MERGE) $(top_srcdir)/po $< $@ -d -u -c
$(top_builddir)/po/.intltool-merge-cache
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ <sect3>
+ <title>Installing the D-Bus service file</title>
+
+ <para>To install the service file the following rule can be placed in the applets
Makefile:</para>
+ <informalexample>
+ <programlisting>
+ servicedir = $(datadir)/dbus-1/services
+ service_in_files = org.gnome.panel.applet.HelloWorldFactory.service.in
+ service_DATA = $(service_in_files:.service.in=.service)
+
+ org.gnome.panel.applet.HelloWorldFactory.service: $(service_in_files)
+ $(AM_V_GEN) sed -e "s|\@LOCATION\@|$(APPLET_LOCATION)|" $< > $@
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ <sect3>
+ <title>Distribution and Cleanup</title>
+ <para>Add panel-applet .in.in and service file to EXTRA_DIST and $(applet_DATA)
$(applet_DATA).in to CLEANFILES</para>
+ <informalexample>
+ <programlisting>
+ EXTRA_DIST = \
+ GNOME_MixerApplet.panel-applet.in.in \
+ $(service_in_files) \
+ $(ui_DATA) \
+ $(schemas_in_files)
+
+ CLEANFILES = $(applet_DATA) $(applet_DATA).in $(service_DATA) $(schemas_DATA)
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ </sect2>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="getting-started.integration">
+ <title>Proper Integration with the Panel</title>
+
+ <para>
+ Since the applets appear as part of the panel to users, it is important that they behave in a
consistent way. A few steps can be completed to achieve proper integration.
+ </para>
+
+ <sect2 id="getting-started.integration.background">
+ <title>Panel Background</title>
+
+ <para>
+ The panel can have different types of background, depending on how the user configures the panel. By
default, applets do not respect the background that is configured and can therefore look out of place.
+ </para>
+
+ <para>
+ The <link
linkend="panel-applet-set-background-widget"><function>panel_applet_set_background_widget()</function></link>
function can be used to automatically have the right background drawn for a specific widget. Just using this
function on the <link linkend="PanelApplet"><type>PanelApplet</type></link> object itself, or its child is
usually enough to have proper background integration.
+ </para>
+
+ <para>
+ In some rare cases, though,
+ <link linkend="panel-applet-set-background-widget">
+ <function>panel_applet_set_background_widget()</function>
+ </link> will not be enough. The solution is then to connect to the
+ <link linkend="PanelApplet-change-background"><function>"change-background"</function></link> signal
of the
+ <link linkend="PanelApplet"><type>PanelApplet</type></link> object: it will be emitted when the
background has
+ changed, and it will provide the <type>cairo_pattern_t</type> pattern to use as a basis to draw the
background.
+ </para>
+
+ </sect2>
+
+ <sect2 id="getting-started.integration.lockdown">
+ <title>Panel Lockdown</title>
+
+ <para>
+ The panel has proper support for lockdown, and when it is locked down, it is expected that all applets
behave
+ consistently in a lockdown mode too. This generally means that the preferences of the applet should
not be
+ accessible, but it could also imply a restriction on the behavior of the applet.
+ </para>
+
+ <para>
+ The <link
linkend="panel-applet-get-locked-down"><function>panel_applet_get_locked_down()</function></link>
+ function can be used to query the state of the panel lockdown. It is also possible to react to changes
by
+ monitoring the <link linkend="PanelApplet--locked-down"><function>"locked-down"</function></link>
+ property of the <link linkend="PanelApplet"><type>PanelApplet</type></link> object. You can achieve
this
+ by connecting to the <function>"notify::locked-down"</function> event.
+ </para>
+
+ <para>
+ In most cases, the <type>GBinding</type> API is enough to respect the panel lockdown:
+ <function>g_object_bind_property()</function> can be used to automatically update the visiblity of a
menu
+ item in the context menu of the applet. In the following example, the
<function>"HelloWorldPrefs"</function>
+ action (which is an action from the context menu) will only be displayed if the panel is not locked
down.
+
+ <informalexample>
+ <programlisting language="c">
+action = gtk_action_group_get_action (action_group, "HelloWorldPrefs");
+g_object_bind_property (applet, "locked-down",
+ action, "visible",
+ G_BINDING_DEFAULT|G_BINDING_INVERT_BOOLEAN|G_BINDING_SYNC_CREATE);
+ </programlisting>
+ </informalexample>
+
+ <para>
+ Of course it is also possible to use <function>g_object_bind_property()</function> to change the
visibility of
+ widgets that appear outside of the context menu, like a button in a window.
+ </para>
+
+ </para>
+
+ </sect2>
+
+ </chapter>
+
+ <chapter id="getting-started.introspection">
+ <title>Writing an applet in languages other than C</title>
+
+ <para>
+ The Panel Applet library comes with support for
+ <ulink url="http://live.gnome.org/GObjectIntrospection";>GObject Introspection</ulink>.
+ This makes it possible to write applets in the languages that have
+ <ulink url="http://live.gnome.org/GObjectIntrospection/Users";>bindings based on GObject
Introspection</ulink>.
+ </para>
+
+ <para>
+ Here is a simple example of a python applet:
+
+ <example>
+ <title>Hello World applet, in Python</title>
+ <programlisting language="python">
+from gi.repository import Gtk
+from gi.repository import PanelApplet
+
+def applet_fill(applet):
+ label = Gtk.Label("Hello World")
+ applet.add(label)
+ applet.show_all()
+
+def applet_factory(applet, iid, data):
+ if iid != "HelloWorldApplet":
+ return False
+
+ applet_fill(applet)
+
+ return True
+
+PanelApplet.Applet.factory_main("HelloWorldFactory",
+ PanelApplet.Applet.__gtype__,
+ applet_factory, None)
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ The only limitation of writing an applet in a language other than C is that the applet will
+ not be able to run in the panel process: it will have to stay out-of-process. However, since
+ it is recommended to leave applets out-of-process, this limitation is mitigated.
+ </para>
+ </chapter>
+
+ </part>
+
+ <part id="port-gnome2">
+ <title>Porting older Applets</title>
+
+ <chapter id="port-gnome2.dbus">
+ <title>Porting to a D-Bus-based Applet</title>
+
+ <sect1 id="port-gnome2.dbus.introduction">
+ <title>Introduction</title>
+ <para>
+ Applets that were written for Gnome 2.x must we ported to be usable with Gnome 3 and the
latest Panel Applet
+ Library. First of all if the applet was written for Gnome 2.x then it will still use GTK+ 2
and must be migrated
+ to GTK+ 3. Please refer to the
+ <ulink url="http://library.gnome.org/devel/gtk3/stable/gtk-migrating-2-to-3.html";>GTK+ 2 to
GTK+ 3 migration guide</ulink>
+ for further details.
+ </para>
+
+ <para>
+ Once the GTK+ 2 to 3 migration has been completed you must migrate the Panel Applet Library
specific
+ parts of the applet. During Gnome 2 times, the Panel Applet Library used LibBonobo, which
was replaced
+ by a DBUS based API during the switch to Panel Applet Library version 4.0. During the change
to
+ version 5.0 additional API have been replaced in particular the GConf related functions have
been
+ removed and were replaced by the GSettings API. Also GtkAction related functions have been
replaced
+ by the GAction API.
+ </para>
+
+ <note>
+ <simpara>
+ The following migration guide is based on the
+ <ulink url="https://wiki.gnome.org/Initiatives/GnomeGoals/AppletsDbusMigration";>
+ AppletsDBUsMigration
+ </ulink> guide in the GNOME Wiki. This guide was originally written for the migration of
GNOME 2
+ applets to GNOME 3 and Panel Applet Library version 4.0. Based on the information of the
+ original guide this section improves some of the explanations, adds references to other
parts
+ of this manual and has been updated for the migration to version 5.0 of this library.
+ </simpara>
+ </note>
+ </sect1>
+
+ <sect1 id="port-gnome2.dbus.remove-libbonobo-factory">
+ <title>Removing LibBonobo factory</title>
+ <para>
+ To migrate from LibBonobo to the DBUS API remove PANEL_APPLET_BONOBO_FACTORY and replace it
with
+ either PANEL_APPLET_OUT_PROCESS_FACTORY or PANEL_APPLET_IN_PROCESS_FACTORY depending if you
want
+ an out-process or in-process applet, respectively.
+ </para>
+ <para>
+ The new macros have the same parameters as the old, except the version and description
parameters have been
+ removed. Also the <constant>OAFIID:GNOME_</constant> prefix of the first parameter can be
dropped both from
+ the factory ID and the applet type name. The following
+ two code listings show the difference between the old and new macro definitions:
+ </para>
+
+ <informalexample>
+ <programlisting>
+ PANEL_APPLET_BONOBO_FACTORY ("OAFIID:GNOME_HelloWorldFactory",
+ PANEL_TYPE_APPLET,
+ "WindowNavigationApplets",
+ "0",
+ hello_world_factory,
+ NULL)
+ </programlisting>
+ </informalexample>
+
+ The new version of the macro should be:
+
+ <informalexample>
+ <programlisting>
+ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+ PANEL_TYPE_APPLET,
+ hello_world_factory,
+ NULL)
+ </programlisting>
+ </informalexample>
+
+ <para>
+ The applet factory callback, in this case the <function>hello_world_factory</function>
usually contains a
+ check to ensure that the applet factory supports the requested applet. Here the
+ <constant>OAFIID:GNOME_</constant> prefix should be dropped as well, see the following two
code listings.
+ </para>
+
+ <note>
+ <simpara>
+ When you drop the prefix here, you must also remove the prefix from the applet name in
the Panel Applet File.
+ </simpara>
+ </note>
+
+ Old definition:
+
+ <informalexample>
+ <programlisting>
+ static gboolean
+ hello_world_factory (PanelApplet *applet,
+ const char *iid,
+ gpointer data)
+ {
+
+ if (!g_strcmp (iid, "OAFIID:GNOME_HelloWorldApplet") != 0)
+ return FALSE;
+
+ hello_world_applet_fill (applet);
+
+ return TRUE;
+ }
+ </programlisting>
+ </informalexample>
+
+ The new version of of the factory callback should be:
+
+ <informalexample>
+ <programlisting>
+ static gboolean
+ hello_world_factory (PanelApplet *applet,
+ const char *iid,
+ gpointer data)
+ {
+
+ if (!g_strcmp0 (iid, "HelloWorldApplet") != 0)
+ return FALSE;
+
+ hello_world_applet_fill (applet);
+
+ return TRUE;
+ }
+ </programlisting>
+ </informalexample>
+
+ <sect2 id="port-gnome2.dbus.migrate-to-panel-applet-file">
+ <title>Migrating Service file to Panel Applet File</title>
+
+ <para>
+ The old applet will have a <constant>service.in.in</constant> file that was used to
register the
+ applet with the GNOME Panel. This file must be renamed to
<constant>.panel-applet</constant> and its
+ content changed to match the format of the new file type. See
+ <link linkend="getting-started.install">Panel Applet Files</link> for a detailed
explanation of the
+ valid fields. If you decided to use the out-process factory macro, then you should also
supply a
+ <link linkend="getting-started.in-out-process">D-BUS Service File</link> so your applet
can be started
+ using D-BUS activation.
+ </para>
+
+ <para>
+ For compatibility you can keep the old <constant>BonoboId</constant>. This field can
contain the old
+ bonobo identifier. It allows the panel to load applets using existing configuration data
in your panels
+ settings. It can be a single string or a list of strings in case of applets with more
than one
+ identifier.
+ </para>
+
+ Example for the migrated panel applet file:
+ <informalexample>
+ <programlisting>
+ [Applet Factory]
+ Id=HellWorldFactory
+ Location=@LOCATION@
+ _Name=Hello World Applet Factory
+ _Description=Factory for the our example applets
+
+ [HelloWorldApplet]
+ _Name=Hello World
+ _Description=Factory for the Hello World example applet
+ Icon=hello-world-icon
+ BonoboId=OAFIID:GNOME_HelloWorldApplet
+ X-GNOME-Bugzilla-Bugzilla=GNOME
+ X-GNOME-Bugzilla-Product=gnome-panel
+ X-GNOME-Bugzilla-Component=hello-world-applet
+ X-GNOME-Bugzilla-Version=@VERSION@
+ X-GNOME-Bugzilla-OtherBinaries=hello-world-applet
+ </programlisting>
+ </informalexample>
+ </sect2>
+ </sect1>
+
+ <sect1 id="port-gnome2.dbus.migrate-menus-to-gaction">
+ <title>Migrating LibBonobo menus to GAction</title>
+ <para>
+ During GNOME 2 days the context menu of the applet was based on the
<constant>BonoboUiVerb</constant>
+ class. These old menu verb definitions have been removed and should be replaced by
+ the <type>GAction</type> interface family of objects.
+
+ <note>
+ <simpara>
+ Previous versions of this migration guide suggested to migrate to the family of
+ <type>GtkActionGroup</type> classes. Since Gtk+ 3.10 these are deprecated and with
the
+ change of the Panel Applet Library API to version 5.0 the
<function>panel_applet_setup_menu</function>
+ family of functions now accept the <type>GActionGroup</type> interface and its
related classes.
+ </simpara>
+ </note>
+ </para>
+
+ If the applet that is being ports had a context menu then it should contain code that looks
similar to the
+ following listing:
+
+ <informalexample>
+ <programlisting>
+ static const BonoboUIVerb show_desktop_menu_verbs [] = {
+ BONOBO_UI_UNSAFE_VERB ("ShowDesktopPreferences", display_preferences_dialog),
+ BONOBO_UI_UNSAFE_VERB ("ShowDesktopAbout", display_about_dialog),
+ BONOBO_UI_VERB_END
+ };
+ </programlisting>
+ </informalexample>
+
+ The new code instead looks like this:
+
+ <informalexample>
+ <programlisting>
+ static const GActionEntry menu_actions[] = {
+ { "preferences", display_preferences_dialog },
+ { "about", display_about_dialog }
+ };
+ </programlisting>
+ </informalexample>
+
+ This change also means that the callbacks must be changed to match the GAction API:
+
+ Old callback looked like this:
+ <informalexample>
+ <programlisting>
+ static void
+ display_preferences_dialog (BonoboUIComponent *uic,
+ gpointer *user_data,
+ const gchar *verbname)
+ </programlisting>
+ </informalexample>
+
+ The new version should have the following signature:
+ <informalexample>
+ <programlisting>
+ static void
+ display_preferences_dialog (GSimpleAction *action,
+ GVariant *parameter,
+ gpointer user_data)
+ </programlisting>
+ </informalexample>
+
+ <para>
+ Additionally you should use GtkBuilder to define a GMenuModel in XML and use the
+ <function>panel_applet_setup_menu</function> family of functions to setup the menu. See
+ <link linkend="getting-started.context-menu">Using a context menu</link> for more details.
+ For more information about using the GMenu and GAction APIs please refer to the GIO Reference
+ Manual.
+ </para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Porting Applets from Panel Applet Library 4.0</title>
+ <para>
+ The Panel Applet Library name has been renamed during the switch from version 4.0 to 5.0 and is
now called
+ <constant>libpanel-applet</constant>.
+ </para>
+ <note>
+ <simpara>
+ Note that the version information in the library name has been dropped and there is now an
+ additional hypen between 'panel' and 'applet'.
+ </simpara>
+ </note>
+
+ <para>
+ GConf support has been removed and was replaced by GSettings. If the applet still uses GConf it
must
+ migrate to GSettings. It is recommended to use the
<function>panel_applet_settings_new()</function> function
+ to store your settings.
+ </para>
+
+ <para>
+ The <function>panel_applet_setup_menu</function> familiy of functions have been changed and now
accept the
+ <type>GActionGroup</type> interface instead of the deprecated <type>GtkActionGroup</type>. Thus
older applets
+ need to be changed and must migrate their menus to the <type>GAction</type> model. Please refer
to the Gtk+
+ documentation for more details about <type>GAction</type> and the related interfaces.
+ </para>
+ </chapter>
+
+ </part>
+
+ <part id="reference">
+ <title>API Reference</title>
+
+ <xi:include href="xml/applet.xml"/>
+ <xi:include href="xml/applet-factory.xml"/>
+ </part>
+
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <index id="api-index-3-4" role="3.4">
+ <title>Index of new symbols in 3.4</title>
+ <xi:include href="xml/api-index-3.4.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <index id="api-index-3-18" role="3.18">
+ <title>Index of new symbols in 3.18</title>
+ <xi:include href="xml/api-index-3.18.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <index id="api-index-3-22" role="3.22">
+ <title>Index of new symbols in 3.22</title>
+ <xi:include href="xml/api-index-3.22.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+
+</book>
diff --git a/doc/reference/libpanel-applet/libpanel-applet-overrides.txt
b/doc/reference/libpanel-applet/libpanel-applet-overrides.txt
new file mode 100644
index 0000000..e69de29
diff --git a/doc/reference/libpanel-applet/libpanel-applet-sections.txt
b/doc/reference/libpanel-applet/libpanel-applet-sections.txt
new file mode 100644
index 0000000..f46760e
--- /dev/null
+++ b/doc/reference/libpanel-applet/libpanel-applet-sections.txt
@@ -0,0 +1,43 @@
+<INCLUDE>panel-applet.h</INCLUDE>
+
+<SECTION>
+<FILE>applet</FILE>
+<TITLE>Panel Applet</TITLE>
+PanelApplet
+PanelAppletOrient
+PANEL_APPLET_ORIENT_FIRST
+PANEL_APPLET_ORIENT_LAST
+PanelAppletFlags
+PANEL_APPLET_FLAGS_ALL
+panel_applet_get_orient
+panel_applet_get_gtk_orientation
+panel_applet_add_text_class
+panel_applet_set_size_hints
+panel_applet_get_flags
+panel_applet_set_flags
+panel_applet_get_locked_down
+panel_applet_settings_new
+panel_applet_request_focus
+panel_applet_setup_menu
+panel_applet_setup_menu_from_file
+panel_applet_setup_menu_from_resource
+<SUBSECTION Standard>
+PANEL_APPLET
+PANEL_IS_APPLET
+PANEL_TYPE_APPLET
+panel_applet_get_type
+PANEL_APPLET_CLASS
+PANEL_IS_APPLET_CLASS
+PANEL_APPLET_GET_CLASS
+<SUBSECTION Private>
+PanelAppletClass
+PanelAppletPrivate
+panel_applet_factory_setup_in_process
+</SECTION>
+
+<SECTION>
+<FILE>applet-factory</FILE>
+<TITLE>Panel Applet Factory</TITLE>
+PanelAppletFactoryCallback
+PANEL_APPLET_IN_PROCESS_FACTORY
+</SECTION>
diff --git a/doc/release-steps.txt b/doc/release-steps.txt
new file mode 100644
index 0000000..7a19fb7
--- /dev/null
+++ b/doc/release-steps.txt
@@ -0,0 +1,150 @@
+ The steps for releasing a module is more or less the same for every
+module. Below, I've described the steps I take when releasing
+gnome-panel, gnome-desktop and gnome-session.
+
+Mark McLoughlin
+14th March, 2003
+
+1) Make sure you're up to date: cvs -z3 update -dP
+
+2) Increment the version number in configure.in e.g. bump
+
+<>
+ AM_INIT_AUTOMAKE(gnome-panel, 2.3.1)
+<>
+
+3) Update the LT_VERSION string if relevant. There's a comment in
+ configure.in that explains how this works:
+
+<>
+# Before making a release, the LT_VERSION string should be modified.
+# The string is of the form C:R:A.
+# - If interfaces have been changed or added, but binary compatibility has
+# been preserved, change to C+1:0:A+1
+# - If binary compatibility has been broken (eg removed or changed interfaces)
+# change to C+1:0:0
+# - If the interface is the same as the previous version, change to C:R+1:A
+
+LIB_PANEL_APPLET_LT_VERSION=0:14:0
+AC_SUBST(LIB_PANEL_APPLET_LT_VERSION)
+<>
+
+ In most cases you won't need to do anything.
+
+4) In the case of gnome-desktop, update:
+
+<>
+GNOME_PLATFORM=2
+GNOME_MINOR=3
+GNOME_MICRO=1
+GNOME_VENDOR="Gnome.Org"
+GNOME_DATE="14th March, 2003"
+<>
+
+ i.e. here I'm doing a release for GNOME 2.3.1 on the 14th of March.
+
+5) Update the version number at the top of the README file.
+
+6) Add an ChangeLog entry e.g.
+
+<>
+2003-03-14 Mark McLoughlin <mark skynet ie>
+
+ * configure.in: Version 2.3.1.
+<>
+
+7) Add an entry to the NEWS file. I use a format like
+
+<>
+=============
+Version 2.3.1
+=============
+
+Panel
+
+ * Blah blah blah
+
+Applets
+
+ ....
+
+Miscellanous
+
+ ....
+
+Translations
+
+ * az(Metin Amiroff), be(Dmitry G. Mastrukov), bg(Alexander Shopov),
+ da(Ole Laursen), eo(Joël Brich), es(Pablo Gonzalo del Campo),
+ .... and zh_TW(Abel Cheung).
+<>
+
+ This is the most time consuming part. First, I do something like:
+
+<>
+$ cvs -z3 diff -uNp -r GNOME_PANEL_2_3_0 > changes.txt
+<>
+
+ to generate a list of changes since the last release. Then you
+ should go through each of the ChangeLogs in the diff and come up
+ with a bullet point for each significant change and credit the
+ person(s) who did the work. Some tips:
+
+ o If several entries relate to the same change only use a single
+ bullet point.
+ o Try to make the bullet points short and snappy but
+ understandable for a general user. That's not always easy.
+ o Generate the list of translations from po/ChangeLog. Note,
+ that the actual translator isn't always the one with who added
+ the ChangeLog entry - try to credit the right person/team. The
+ format is "$locale($translator)". Sort alphabetically by
+ locale.
+
+8) Do a autogen && make && make install && make distcheck. Fix any
+ issues that crop up. Hopefully there are none because they can be a
+ right PITA - especially distcheck errors.
+
+9) While that's churning, compose a mail to
+ desktop-devel-list gnome org, release-team gnome org and
+ gnome-announce-list gnome org. I use the crappy template below:
+
+<>
+http://mail.gnome.org/archives/desktop-devel-list/2003-March/msg00331.html
+<>
+
+ Just copy the NEWS entries in and change the locations on the ftp
+ server.
+
+10) Distcheck finishes:
+
+<>
+==================================================
+gnome-panel-2.3.1.tar.gz is ready for distribution
+==================================================
+<>
+
+ Yay !
+
+11) Do a cvs commit. If that fails because someone has committed since
+ you last updated, then you'll need to repeat the whole thing
+ again. Well, update, add a new NEWS entry, and make distcheck
+ again.
+
+12) Tag the release. e.g. cvs tag GNOME_PANEL_2_3_1.
+
+13) Add version markers to all ChangeLogs e.g.:
+
+<>
+==================== 2.2.2 ====================
+
+2003-05-20 The Little Green Man <greenman littlepeople org>
+
+ * pot-o-gold.c: add ability to theme the pot.
+<>
+
+14) Upload the tarball to ftp.gnome.org and install-module the
+ tarball. No command-line args are required.
+
+15) Send the mail to the lists.
+
+16) Get yourself a joffee and mutter "I hate doing this fscking crap".
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
