1 files changed, 250 insertions, 0 deletions
diff --git a/doc/panel-session-handling.txt b/doc/panel-session-handling.txt
new file mode 100644
index 00000000..3f20e04f
--- /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 MateConf 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 MateConf 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 mate-core, and the (to
+be written by hp) mateconf 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 MateConf 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 MateConf, 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 MateConf 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 MateConf in a key such as:
+
+ /apps/applet/deskguide/grouping_limit
+
+Global settings have normal MateConf 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 MateConf 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 MateConf 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 mateconf, use the default value. The way to
+use this is to call mateconf_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 mateconf calls in some utility functions like
+this: 
+
+gint
+applet_mateconf_get_int_with_default (SomeAppletType *applet,
+ const gchar* key,
+ gint default,
+ GError** err)
+{
+ GError* error = NULL;
+ MateConfValue* val;
+ MateConfClient *client = panel_mateconf_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, MATECONF_VALUE_INT, &error))
+ retval = mateconf_value_get_int(val);
+ else
+ handle_error(client, error, err);
+
+ mateconf_value_free(val);
+
+ return retval;
+ }
+ else
+ return default;
+}
+
+And the applet would use this like this
+
+#define TOOLTIP_TIMEOUT_DEFAULT 100 /* msec */
+
+ timeout = applet_mateconf_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 MateConf cleanup needed, or no session id
+thrown about at all.
+
+
+Full example MateConf 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/