From c51ef797a707f4e2c6f9688d4378f2b0e9898a66 Mon Sep 17 00:00:00 2001 From: Perberos Date: Thu, 1 Dec 2011 22:56:10 -0300 Subject: moving from https://github.com/perberos/mate-desktop-environment --- .../tmpl/mate-panel-applet-mateconf.sgml | 263 ++++++++++++++ .../tmpl/mate-panel-applet-unused.sgml | 109 ++++++ .../mate-panel-applet/tmpl/mate-panel-applet.sgml | 393 +++++++++++++++++++++ 3 files changed, 765 insertions(+) create mode 100644 doc/reference/mate-panel-applet/tmpl/mate-panel-applet-mateconf.sgml create mode 100644 doc/reference/mate-panel-applet/tmpl/mate-panel-applet-unused.sgml create mode 100644 doc/reference/mate-panel-applet/tmpl/mate-panel-applet.sgml (limited to 'doc/reference/mate-panel-applet/tmpl') diff --git a/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-mateconf.sgml b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-mateconf.sgml new file mode 100644 index 00000000..2ff1e459 --- /dev/null +++ b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-mateconf.sgml @@ -0,0 +1,263 @@ + +Panel Applet MateConf Utilities + + +Utility methods for manipulating per-applet MateConf preferences. + + + +Applets typically define a set of preferences using a schemas +file and mate_panel_applet_add_preferences(). Such preferences apply +only to an individual applet instance. For example, you may add +two clock applets to the panel and configure them differently. + + + +In order for the preferences to only apply to a single applet, +each applet must have a seperate MateConf key for each of these +preferences. The methods described below provide convient wrappers +around the usual #MateConfClient functions and operate on these +per-applet keys. + + + + + + + + + + + + + + +Access the full path for an individual per-applet MateConf key. Using +the returned path you may directly modify the preference using +the usual MateConf functions without using any of the convenience +wrappers described below. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@Returns: The full MateConf key - free using g_free(). + + + + +Convience wrapper for mateconf_client_get_bool() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_bool() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@opt_error: Optional #GError**. +@Returns: The bool value of the key. + + + + +Convience wrapper for mateconf_client_get_int() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_int() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@opt_error: Optional #GError**. +@Returns: The integer value of the key. + + + + +Convience wrapper for mateconf_client_get_string() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_string() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@opt_error: Optional #GError**. +@Returns: The string value of the key, or %NULL if unset. + + + + +Convience wrapper for mateconf_client_get_float() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_float() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@opt_error: Optional #GError**. +@Returns: The floating point value of the key. + + + + +Convience wrapper for mateconf_client_get_list() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_list() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@list_type: The MateConf value type of the list elements. +@opt_error: Optional #GError**. +@Returns: The list of values set for the key. + + + + +Convience wrapper for mateconf_client_get_value() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_get_value() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@opt_error: Optional #GError**. +@Returns: The MateConf value set for the key. + + + + +Convience wrapper for mateconf_client_set_bool() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_bool() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@the_bool: The boolean value to set the key with. +@opt_error: Optional #GError**. + + + + +Convience wrapper for mateconf_client_set_int() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_int() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@the_int: The integer value to set the key with. +@opt_error: Optional #GError**. + + + + +Convience wrapper for mateconf_client_set_string() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_string() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@the_string: The string value to set the key with. +@opt_error: Optional #GError**. + + + + +Convience wrapper for mateconf_client_set_float() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_float() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@the_float: The floating point value to set the key with. +@opt_error: Optional #GError**. + + + + +Convience wrapper for mateconf_client_set_list() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_list() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@list_type: The MateConf value type of the list items. +@list: The list of values to set the key with. +@opt_error: Optional #GError**. + + + + +Convience wrapper for mateconf_client_set_value() which operates +on the individual per-applet key. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which mateconf_client_set_value() +returns. + + +@applet: The #MatePanelApplet. +@key: The key name of the preference. +@value: The MateConf value to set the key with. +@opt_error: Optional #GError**. + + diff --git a/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-unused.sgml b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-unused.sgml new file mode 100644 index 00000000..f184f7f2 --- /dev/null +++ b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet-unused.sgml @@ -0,0 +1,109 @@ + + +Defines a 'main' routine for the applet factory. + + +@iid: The matecomponent-activation iid of the factory. +@type: The #GType to instantiate. +@name: The applet ID string. +@version: The applet version string. +@callback: The factory callback. +@data: The factory user data pointer. + + + +Defines a MateComponent Activation shared library plugin and associated +factory callback. + + +@iid: The matecomponent-activation iid of the factory. +@type: The #GType to instantiate. +@descr: A description of the applet. +@callback: The factory callback. +@data: The factory user data pointer. + + + +The applet is orientated down (i.e. the panel is at the top of the screen). + + + + + +The applet is orientated left (i.e. the panel is at the right hand side of the screen). + + + + + +The applet is orientated right (i.e. the panel is at the left hand side of the screen). + + + + + +The applet is orientated up (i.e. the panel is at the bottom of the screen). + + + + + +A generic 'main' routine for applets. This should not normally be +used directly because it is invoked by #MATE_PANEL_APPLET_MATECOMPONENT_FACTORY. + + +@iid: The matecomponent-activation iid of the factory. +@applet_type: The #GType to instantiate. +@closure: The factory callback closure. +@Returns: 0 on success, 1 on failure. + + + +Retrieves the #MateComponentControl associated with @applet. + + +@applet: The #MatePanelApplet. +@Returns: A #MateComponentControl. + + + +Retrieves the #MateComponentUIComponent used for popup menus associated +with @applet. + + +@applet: The #MatePanelApplet. +@Returns: A #MateComponentUIComponent. + + + +A generic shared library factory routine for applets. This should not +normally be used directly as it is invoked by #MATE_PANEL_APPLET_MATECOMPONENT_SHLIB_FACTORY. + + +@iid: The matecomponent-activation iid of the factory. +@applet_type: The #GType to instantiate. +@poa: The #PortableServer_POA passed to the shlib factory +callback. +@impl_ptr: The #gpointer passed to the shlib factory callback. +@callback: The applet factory callback. +@user_data: The factory user data pointer. +@ev: The $CORBA_Environment passed to the shlib factory callback. +@Returns: A #MateComponent_Unknown to return from the shlib factory +callback. + + + +A generic shared library factory routine for applets. This should not +normally be used directly as it is invoked by #MATE_PANEL_APPLET_MATECOMPONENT_SHLIB_FACTORY. + + +@iid: The matecomponent-activation iid of the factory. +@applet_type: The #GType to instantiate. +@poa: The #PortableServer_POA passed to the shlib factory +callback. +@impl_ptr: The #gpointer passed to the shlib factory callback. +@closure: The applet factory closure. +@ev: The $CORBA_Environment passed to the shlib factory callback. +@Returns: A #MateComponent_Unknown to return from the shlib factory +callback. + diff --git a/doc/reference/mate-panel-applet/tmpl/mate-panel-applet.sgml b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet.sgml new file mode 100644 index 00000000..01d72e2d --- /dev/null +++ b/doc/reference/mate-panel-applet/tmpl/mate-panel-applet.sgml @@ -0,0 +1,393 @@ + +MatePanelApplet + + +The MatePanelApplet object. + + + +The #MatePanelApplet object is an object which encapsulates an applet. It +is a #GtkContainer which may contain a single widget. This widget, in +turn, should contain all widgets exposed by the applet. + + + +A #MatePanelApplet is associated with a #MateComponentControl. The control makes +the cross process UI emmbedding required by applets possible. + + + + + + + + + + + + + + + +The #MatePanelApplet struct contains private data only. + + + + + +Emitted when the background of the panel changes. Use @type to +determine which, if any, of @color and @pimxap is valid. + + +@matepanelapplet: The object which received the signal. +@arg1: +@arg2: +@arg3: + +@type: The #MatePanelAppletBackgroundType. +@color: The #GdkColor if @type is #PANEL_COLOR_BACKGROUND. +@pixmap: The pixmap file name if @type is #PANEL_PIXMAP_BACKGROUND + + + +Emitted when the orientation of the panel changes. + + +@matepanelapplet: The object which received the signal. +@orient: The new #MatePanelAppletOrient of the applet. + + + +Emitted when the size of the panel changes. + + + +Note: this is different for size negotiation which is handled by +size_request() and size_allocate() as usual. This signal should +be used to determine what font size or widget layout to use +depending on the size of the panel. See mate_panel_applet_get_size(). + + +@matepanelapplet: The object which received the signal. +@size: The size hint of the panel. + + + +Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves. + + +@matepanelapplet: The object which received the signal. +@direction: The direction of focus movement. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The #MatePanelAppletOrient type specifies the orientation of the applet. The +values may seem backward (e.g. %MATE_PANEL_APPLET_ORIENT_LEFT means the panel +is on the right hand side), but this is because the value is representative +of the applet's orientation, not the panel's position. + + +@MATE_PANEL_APPLET_ORIENT_UP: +@MATE_PANEL_APPLET_ORIENT_DOWN: +@MATE_PANEL_APPLET_ORIENT_LEFT: +@MATE_PANEL_APPLET_ORIENT_RIGHT: + + + +The #MatePanelAppletBackgroundType enumerated type specifies the type of +background of a panel. + + +@PANEL_NO_BACKGROUND: The panel has no background, the default is used. +@PANEL_COLOR_BACKGROUND: The panel has a color, i.e rgb value, +background. +@PANEL_PIXMAP_BACKGROUND: The panel has either an image background +or is translucent. + + + +The #MatePanelAppletFlags associated with the applet are boolean flags which +the panel may read in order to figure out how to handle the applet. + + +@MATE_PANEL_APPLET_FLAGS_NONE: No flags are to be associated with the applet. +@MATE_PANEL_APPLET_EXPAND_MAJOR: The applet should expand horizontally on an +horizontal panel and vertically on a vertical panel - e.g. the behaviour +of the Window List applet. +@MATE_PANEL_APPLET_EXPAND_MINOR: The applet should expand vertically on an +horizontal panel and horizontally on a vertical panel. Most applets should +set this flag in order to utilise the full panel width and allow the applet +to be Fitt's Law compliant. +@MATE_PANEL_APPLET_HAS_HANDLE: The panel should draw a grab handle around the +applet - e.g. the Window List and Notification Area applets both set this +flag. + + + +This callback is invoked when the applet is loaded onto the panel. Typically +the callback will check that @iid matches and fill the @applet with the +widgets which make up the applet. + + + +Prior to the callback being invoked the #MatePanelApplet (or an instance of the +sub-class specified by the #GType passed to the factory macros) is instantiated +and initialized. + + +@applet: The #MatePanelApplet. +@iid: The MateComponent IID of the applet requested. +@user_data: The data passed to the factory macros. +@Returns: %TRUE on success, %FALSE on failure. + + + + +Creates a new #MatePanelApplet. This function is typically not +useful as the applet is created before the #MatePanelAppletFactoryCallback +is invoked. + + +@void: +@Returns: The #MatePanelApplet. + + + + +Get the current orientation of the applet. + + +@applet: The #MatePanelApplet. +@Returns: The orientation of the applet. + + + + +Get the current size hint for the panel. The size hint is +not useful for most applets. + + + +Note: The return value is not an integer value +specifying the pixel size of the panel. Do not +use this value to calculate the size of the applet. Use it +only as a hint by which to decide the applet's layout. + + +@applet: The #MatePanelApplet. +@Returns: The panel's size hint. + + + + +Returns the current background type. If the background +type is %PANEL_NO_BACKGROUND both @color and @pixmap will +be unaffected. If the background type is %PANEL_COLOR_BACKGROUND +then @color will contain the current panel background colour. +If the background type is %PANEL_PIXMAP_BACKGROUND, @pixmap will +contain a pointer to a #GdkPixmap which is a copy of the applet's +portion of the panel's background pixmap. + + + + +@applet: A #MatePanelApplet. +@color: A #GdkColor to be filled in. +@pixmap: Returned #GdkPixmap. +@Returns: The background type. + + + + +Returns the MateConf path to the directory containing the applet's +per-instance preference keys. Using this you may construct the +full path for the applet's preference keys. See + for +more information. + + +@applet: The #MatePanelApplet. +@Returns: A MateConf path. + + + + +Associates each schema in @schema_dir with a key in the applet's +preferences directory (i.e. the directory returned by +mate_panel_applet_get_preferences_key()). Each applet preference +should have an associated schema to ensure that the key has +a defined type, sane default and documentation. + + + +If you pass %NULL for @opt_error, this function will print +a warning message from any #GError which MateConf may return. + + +@applet: The #MatePanelApplet. +@schema_dir: The MateConf path where the applet's schemas are installed +e.g. /schemas/apps/my_applet +@opt_error: Optional #GError. + + + + +Retrieve the #MatePanelAppletFlags associated with the applet. + + +@applet: The #MatePanelApplet. +@Returns: The #MatePanelAppletFlags. + + + + +Set the #MatePanelAppletFlags associated with the applet. See +#MatePanelAppletFlags for more details on the possible uses of +these flags. + + +@applet: The #MatePanelApplet. +@flags: The #MatePanelAppletFlags to associate. + + + + +Set a list of desired size ranges for an applet with the +#MATE_PANEL_APPLET_EXPAND_MAJOR flags set. @size_hints is an +array of (max, min) pairs where min(i) > max(i + 1). + + + +The panel will endeavour to allocate the applet a size +in one of the (@base + max, @base + min) ranges. + + +@applet: The #MatePanelApplet. +@size_hints: Array of size_hints. +@n_elements: Number of elements in the array. +Not the number of pairs. +@base_size: The base size of the applet. + + + + +Check if the @applet is locked down. A locked down applet should not allow any change to its configuration. + + +@applet: The #MatePanelApplet. +@Returns: %TRUE if the @applet is locked down, %FALSE otherwise. + + + + +Set keyboard focus to @applet. + + +@applet: The #MatePanelApplet. +@timestamp: timestamp of the event triggering the window focus + + + + +Sets up a popup menu for @applet described by the xml +string, @xml. See section +for a description of the format of the xml. + + +@applet: A #MatePanelApplet. +@xml: The xml character string describing the popup menu. +@action_group: + +@verb_list: The list of #MateComponentUIVerbs for the menu. +@user_data: The user data pointer for the menu. + + + + +Sets up a popup menu for @applet described by the xml +file, @file. See for a description of +the format of the xml. + + +@applet: A #MatePanelApplet. +@filename: +@action_group: + +@opt_datadir: The data directory - i.e. ${prefix}/share (optional). +@file: The file's name. +@opt_app_name: The application's name (optional). +@verb_list: The list of #MateComponentUIVerbs for the menu. +@user_data: The user data pointer for the menu. + + + + +A generic 'main' routine for applets. This should not normally be +used directly because it is invoked by #MATE_PANEL_APPLET_MATECOMPONENT_FACTORY. + + +@factory_id: +@out_process: +@applet_type: The #GType to instantiate. +@callback: The factory callback. +@data: The factory user data pointer. +@Returns: 0 on success, 1 on failure. + +@iid: The matecomponent-activation iid of the factory. + + -- cgit v1.2.1