Commit 0e99e3fd authored by Philip Withnall's avatar Philip Withnall

Bug 578387 – Remaining API documentation additions

This adds a load of .h files to the ignore list, and documents the remaining
functions which would be useful to plugins.

It makes TOTEM_MAX_RECENT_ITEM_LEN private to totem-menu.c, since that was the
only file which used it.

It also removes a completely unused declaration of bacon_cd_selection_create
from totem-preferences.h.

See the changes to totem-sections.txt for the list of API I've considered
useful to expose (by way of documentation) to plugins.
parent 223e3def
......@@ -64,6 +64,37 @@ IGNORE_HFILES += \
baconvideowidget-marshal.h \
bacon-video-widget-gst-missing-plugins.h
# Files we don't want exported to plugins
IGNORE_HFILES += \
bacon-video-widget-common.h \
baconvideowidget-marshal.h \
bacon-video-widget-gst-missing-plugins.h \
bacon-resize.h \
totem-playlist.h \
totem-fullscreen.h \
totem-module.h \
totem-time-label.h \
totem-plugin-manager.h \
totem-properties-view.h \
totem-open-location.h \
totem-python-module.h \
totem-statusbar.h \
totem-sidebar.h \
totem-session.h \
totem-resources.h \
totem-plugins-engine.h \
totem-options.h \
totem-preferences.h \
totem-dvb-setup.h \
gstscreenshot.h \
totem-uri.h \
totem-python-plugin.h \
totem-subtitle-encoding.h \
totem-menu.h \
video-utils.h \
debug.h \
totem-dnd-menu.h
# Plugin files
IGNORE_HFILES += \
bacon-video-widget-properties.h \
......
<SECTION>
<FILE>totem-object</FILE>
<TITLE>TotemObject</TITLE>
Totem
TotemObject
TotemObjectClass
TotemRemoteCommand
TotemRemoteSetting
TOTEM_GCONF_PREFIX
totem_object_plugins_init
totem_object_plugins_shutdown
totem_file_opened
......@@ -22,17 +25,23 @@ totem_action_fullscreen
totem_action_fullscreen_toggle
totem_action_next
totem_action_previous
totem_action_next_angle
totem_action_remote_get_setting
totem_action_remote_set_setting
totem_action_seek_time
totem_action_seek_relative
totem_action_volume_relative
totem_action_volume_toggle_mute
totem_action_toggle_aspect_ratio
totem_action_get_aspect_ratio
totem_action_set_aspect_ratio
totem_action_toggle_controls
totem_action_set_scale_ratio
totem_action_set_playlist_index
totem_action_remote
totem_is_fullscreen
totem_is_playing
totem_is_paused
totem_is_seekable
totem_get_main_window
totem_get_ui_manager
......@@ -41,6 +50,10 @@ totem_get_video_widget_backend_name
totem_get_current_mrl
totem_get_current_time
totem_set_current_subtitle
totem_get_playlist_length
totem_get_playlist_pos
totem_get_short_title
totem_get_title_at_playlist_pos
totem_add_sidebar_page
totem_remove_sidebar_page
<SUBSECTION Standard>
......@@ -50,12 +63,35 @@ TOTEM_TYPE_OBJECT
totem_object_get_type
TOTEM_OBJECT_CLASS
TOTEM_IS_OBJECT_CLASS
TOTEM_DISC_MEDIA_TYPE
totem_disc_media_type_get_type
totem_disc_media_type_quark
TOTEM_REMOTE_COMMAND
TOTEM_TYPE_DISC_MEDIA_TYPE
TOTEM_TYPE_REMOTE_COMMAND
totem_remote_command_get_type
totem_remote_command_quark
<SUBSECTION Private>
totem_action_set_mrl
totem_action_set_mrl_and_play
totem_action_set_mrl_with_warning
</SECTION>
<SECTION>
<FILE>totem-interface</FILE>
<TITLE>Interface</TITLE>
totem_interface_error
totem_interface_error_blocking
totem_interface_error_with_link
totem_interface_boldify_label
totem_interface_italicise_label
<SUBSECTION Private>
totem_interface_get_full_path
totem_interface_get_license
totem_interface_load
totem_interface_load_pixbuf
totem_interface_load_with_full_path
totem_interface_set_transient_for
</SECTION>
<SECTION>
......@@ -64,6 +100,13 @@ totem_interface_error_with_link
TotemPlugin
TotemPluginClass
TotemPluginError
TotemPluginActivationFunc
TotemPluginDeactivationFunc
TotemPluginWidgetFunc
TOTEM_PLUGIN_DEFINE_TYPE
TOTEM_PLUGIN_REGISTER
TOTEM_PLUGIN_REGISTER_EXTENDED
TOTEM_PLUGIN_REGISTER_TYPE
totem_plugin_activate
totem_plugin_deactivate
totem_plugin_create_configure_dialog
......@@ -78,8 +121,16 @@ totem_plugin_get_type
TOTEM_PLUGIN_GET_CLASS
TOTEM_PLUGIN_CLASS
TOTEM_IS_PLUGIN_CLASS
TOTEM_PLUGIN_CONST
TOTEM_PLUGIN_ERROR
register_totem_plugin
totem_plugin_error_get_type
totem_plugin_error_quark
TOTEM_TYPE_PLUGIN_ERROR
<SUBSECTION Private>
TotemPluginPrivate
totem_get_plugin_paths
TotemPluginBooleanFunc
</SECTION>
<SECTION>
......@@ -128,6 +179,7 @@ BvwAspectRatio
BvwAudioOutType
BvwDVDEvent
BvwMetadataType
BvwVisualsQuality
BvwVideoProperty
BvwError
BvwUseType
......@@ -196,6 +248,7 @@ bacon_video_widget_is_seekable
<SUBSECTION Standard>
bacon_video_widget_error_quark
bacon_video_widget_get_type
BVW_ERROR
BACON_TYPE_VIDEO_WIDGET
BACON_VIDEO_WIDGET
BACON_VIDEO_WIDGET_CLASS
......
......@@ -292,6 +292,7 @@ void bacon_video_widget_get_metadata (BaconVideoWidget *bvw,
* @VISUAL_NORMAL: normal size (320×25)
* @VISUAL_LARGE: large size (480×25)
* @VISUAL_EXTRA_LARGE: extra large size (600×30)
* @NUM_VISUAL_QUALITIES: the number of visual qualities available
*
* The different visualisation sizes or qualities available for use
* with bacon_video_widget_set_visuals_quality().
......
......@@ -55,9 +55,49 @@ typedef struct {
GObject parent;
} TotemPlugin;
/**
* TotemPluginActivationFunc:
* @plugin: the #TotemPlugin
* @totem: a #TotemObject
* @error: a #GError
*
* Called when the user has requested @plugin be activated, this function should be used to initialise
* any resources the plugin needs, and attach itself to the Totem UI.
*
* If an error is encountered while setting up the plugin, @error should be set, and the function
* should return %FALSE. Totem will then not mark the plugin as activated, and will ensure it's not loaded
* again unless explicitly asked for by the user.
*
* Return value: %TRUE on success, %FALSE otherwise
**/
typedef gboolean (*TotemPluginActivationFunc) (TotemPlugin *plugin, TotemObject *totem,
GError **error);
/**
* TotemPluginDeactivationFunc:
* @plugin: the #TotemPlugin
* @totem: a #TotemObject
*
* Called when the user has requested @plugin be deactivated, this function should destroy all resources
* created during the plugin's lifetime, especially those created in the activation function.
*
* It should be possible to activate and deactivate the plugin multiple times sequentially in a single Totem
* session without memory or resource leaks, or errors.
**/
typedef void (*TotemPluginDeactivationFunc) (TotemPlugin *plugin, TotemObject *totem);
/**
* TotemPluginWidgetFunc:
* @plugin: the #TotemPlugin
*
* Called when the configuration dialogue for the plugin needs to be built, this function should return
* a complete window which will be shown by the Totem code. The widget needs to be capable of hiding itself
* when configuration is complete.
*
* If your plugin is not configurable, do not define this function.
*
* Return value: a #GtkWidget
**/
typedef GtkWidget * (*TotemPluginWidgetFunc) (TotemPlugin *plugin);
typedef gboolean (*TotemPluginBooleanFunc) (TotemPlugin *plugin);
......@@ -133,15 +173,33 @@ GtkBuilder * totem_plugin_load_interface (TotemPlugin *plugin,
GList * totem_get_plugin_paths (void);
/*
* Utility macro used to register plugins
/**
* TOTEM_PLUGIN_REGISTER:
* @PluginName: the plugin's name in camelcase
* @plugin_name: the plugin's name in lowercase, with underscores
*
* use: TOTEM_PLUGIN_REGISTER(TOTEMSamplePlugin, totem_sample_plugin)
*/
* Registers a new Totem plugin type. A plugin is, at its core, just a class which is
* instantiated and activated on the user's request. This macro registers that class.
**/
#define TOTEM_PLUGIN_REGISTER(PluginName, plugin_name) \
TOTEM_PLUGIN_REGISTER_EXTENDED(PluginName, plugin_name, {})
/**
* TOTEM_PLUGIN_REGISTER_EXTENDED:
* @PluginName: the plugin's name in camelcase
* @plugin_name: the plugin's name in lowercase, with underscores
* @_C_: extra code to call in the module type registration function
*
* Registers a new Totem plugin type with custom code in the module type registration
* function. See TOTEM_PLUGIN_REGISTER() for more information about the registration
* process.
*
* A variable named @our_info is available with the module's #GTypeInfo information.
* @plugin_module_type is the plugin's #GTypeModule.
* @<replaceable>plugin_name</replaceable>_type is the plugin's newly-registered #GType
* (where <replaceable>plugin_name</replaceable> is the plugin name passed to the
* TOTEM_PLUGIN_REGISTER_EXTENDED() macro).
**/
#define TOTEM_PLUGIN_REGISTER_EXTENDED(PluginName, plugin_name, _C_) \
_TOTEM_PLUGIN_REGISTER_EXTENDED_BEGIN (PluginName, plugin_name) {_C_;} _TOTEM_PLUGIN_REGISTER_EXTENDED_END(plugin_name)
......@@ -200,9 +258,25 @@ register_totem_plugin (GTypeModule *module) \
return plugin_name##_type; \
}
/**
* TOTEM_PLUGIN_REGISTER_TYPE:
* @type_name: the type's name in lowercase, with underscores
*
* Calls the type registration function for a type inside a plugin module previously
* defined with TOTEM_PLUGIN_DEFINE_TYPE().
**/
#define TOTEM_PLUGIN_REGISTER_TYPE(type_name) \
type_name##_register_type (plugin_module_type)
/**
* TOTEM_PLUGIN_DEFINE_TYPE:
* @TypeName: the type name in camelcase
* @type_name: the type name in lowercase, with underscores
* @TYPE_PARENT: the type's parent name in uppercase, with underscores
*
* Registers a type to be used inside a Totem plugin, but not the plugin's itself;
* use TOTEM_PLUGIN_REGISTER() for that.
**/
#define TOTEM_PLUGIN_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT) \
static void type_name##_init (TypeName *self); \
static void type_name##_class_init (TypeName##Class *klass); \
......
......@@ -78,6 +78,15 @@ totem_interface_error_dialog (const char *title, const char *reason,
return error_dialog;
}
/**
* totem_interface_error:
* @title: the error title
* @reason: the error reason (secondary text)
* @parent: the error dialogue's parent #GtkWindow
*
* Display a modal error dialogue with @title as its primary error text, and @reason
* as its secondary text.
**/
void
totem_interface_error (const char *title, const char *reason,
GtkWindow *parent)
......@@ -92,6 +101,15 @@ totem_interface_error (const char *title, const char *reason,
gtk_window_present (GTK_WINDOW (error_dialog));
}
/**
* totem_interface_error_blocking:
* @title: the error title
* @reason: the error reason (secondary text)
* @parent: the error dialogue's parent #GtkWindow
*
* Display a modal error dialogue like totem_interface_error() which blocks until the user has
* dismissed it.
**/
void
totem_interface_error_blocking (const char *title, const char *reason,
GtkWindow *parent)
......@@ -147,7 +165,7 @@ link_button_clicked_cb (GtkWidget *widget, Totem *totem)
* @parent: the error dialogue's parent #GtkWindow
* @totem: a #TotemObject
*
* Display a modal error dialogue like totem_interface_error_dialog(),
* Display a modal error dialogue like totem_interface_error(),
* but add a button which will open @uri in a browser window.
**/
void
......@@ -354,6 +372,18 @@ totem_interface_get_license (void)
NULL);
}
/**
* totem_interface_boldify_label:
* @builder: a #GtkBuilder
* @name: the label name
*
* Makes the text of the @name label bold.
*
* This should be used instead of putting the Pango markup directly into a #GtkBuilder
* UI file so that translators don't have to translate text formatting markup unnecessarily.
*
* This function can only be used if the entire text of a label is to be made bold.
**/
void
totem_interface_boldify_label (GtkBuilder *builder, const char *name)
{
......@@ -388,6 +418,18 @@ totem_interface_boldify_label (GtkBuilder *builder, const char *name)
g_free (str_final);
}
/**
* totem_interface_italicise_label:
* @builder: a #GtkBuilder
* @name: the label name
*
* Makes the text of the @name label italic.
*
* This should be used instead of putting the Pango markup directly into a #GtkBuilder
* UI file so that translators don't have to translate text formatting markup unnecessarily.
*
* This function can only be used if the entire text of a label is to be made italic.
**/
void
totem_interface_italicise_label (GtkBuilder *builder, const char *name)
{
......
......@@ -53,10 +53,10 @@ void totem_interface_error_with_link (const char *title,
void totem_interface_set_transient_for (GtkWindow *window,
GtkWindow *parent);
char * totem_interface_get_license (void);
void totem_interface_boldify_label (GtkBuilder *xml,
const char *label);
void totem_interface_italicise_label(GtkBuilder *xml,
const char *label);
void totem_interface_boldify_label (GtkBuilder *builder,
const char *name);
void totem_interface_italicise_label(GtkBuilder *builder,
const char *name);
G_END_DECLS
......
......@@ -36,6 +36,8 @@
#include "debug.h"
#define TOTEM_MAX_RECENT_ITEM_LEN 40
/* Callback functions for GtkBuilder */
G_MODULE_EXPORT void open_action_callback (GtkAction *action, Totem *totem);
G_MODULE_EXPORT void open_location_action_callback (GtkAction *action, Totem *totem);
......
......@@ -27,8 +27,6 @@
G_BEGIN_DECLS
#define TOTEM_MAX_RECENT_ITEM_LEN 40
void totem_ui_manager_setup (Totem *totem);
void totem_sublang_update (Totem *totem);
......
......@@ -491,6 +491,14 @@ totem_get_current_mrl (Totem *totem)
return totem_playlist_get_current_mrl (totem->playlist, NULL);
}
/**
* totem_get_playlist_length:
* @totem: a #TotemObject
*
* Returns the length of the current playlist.
*
* Return value: the playlist length
**/
guint
totem_get_playlist_length (Totem *totem)
{
......@@ -502,18 +510,44 @@ totem_get_playlist_length (Totem *totem)
return last + 1;
}
/**
* totem_get_playlist_pos:
* @totem: a #TotemObject
*
* Returns the %0-based index of the current entry in the playlist. If
* there is no current entry in the playlist, %-1 is returned.
*
* Return value: the index of the current playlist entry, or %-1
**/
int
totem_get_playlist_pos (Totem *totem)
{
return totem_playlist_get_current (totem->playlist);
}
/**
* totem_get_title_at_playlist_pos:
* @totem: a #TotemObject
* @index: the %0-based entry index
*
* Gets the title of the playlist entry at @index.
*
* Return value: the entry title at @index, or %NULL; free with g_free()
**/
char *
totem_get_title_at_playlist_pos (Totem *totem, guint index)
{
return totem_playlist_get_title (totem->playlist, index);
}
/**
* totem_get_short_title:
* @totem: a #TotemObject
*
* Gets the title of the current entry in the playlist.
*
* Return value: the current entry's title, or %NULL; free with g_free()
**/
char *
totem_get_short_title (Totem *totem)
{
......@@ -2797,6 +2831,13 @@ totem_action_toggle_controls (Totem *totem)
gtk_toggle_action_set_active (GTK_TOGGLE_ACTION (action), !state);
}
/**
* totem_action_next_angle:
* @totem: a #TotemObject
*
* Switches to the next angle, if watching a DVD. If not watching a DVD, this is a
* no-op.
**/
void
totem_action_next_angle (Totem *totem)
{
......@@ -2804,6 +2845,17 @@ totem_action_next_angle (Totem *totem)
bacon_video_widget_dvd_event (totem->bvw, BVW_DVD_NEXT_ANGLE);
}
/**
* totem_action_set_playlist_index:
* @totem: a #TotemObject
* @index: the new playlist index
*
* Sets the %0-based playlist index to @index, causing Totem to load and
* start playing that playlist entry.
*
* If @index is higher than the current length of the playlist, this
* has the effect of restarting the current playlist entry.
**/
void
totem_action_set_playlist_index (Totem *totem, guint index)
{
......@@ -2996,6 +3048,14 @@ totem_action_remote (Totem *totem, TotemRemoteCommand cmd, const char *url)
}
}
/**
* totem_action_remote_set_setting:
* @totem: a #TotemObject
* @setting: a #TotemRemoteSetting
* @value: the new value for the setting
*
* Sets @setting to @value on this instance of Totem.
**/
void totem_action_remote_set_setting (Totem *totem,
TotemRemoteSetting setting,
gboolean value)
......@@ -3018,6 +3078,15 @@ void totem_action_remote_set_setting (Totem *totem,
gtk_toggle_action_set_active (GTK_TOGGLE_ACTION (action), value);
}
/**
* totem_action_remote_get_setting:
* @totem: a #TotemObject
* @setting: a #TotemRemoteSetting
*
* Returns the value of @setting for this instance of Totem.
*
* Return value: %TRUE if the setting is enabled, %FALSE otherwise
**/
gboolean totem_action_remote_get_setting (Totem *totem,
TotemRemoteSetting setting)
{
......@@ -3167,6 +3236,14 @@ totem_is_playing (Totem *totem)
return bacon_video_widget_is_playing (totem->bvw) != FALSE;
}
/**
* totem_is_paused:
* @totem: a #TotemObject
*
* Returns %TRUE if playback is paused.
*
* Return value: %TRUE if playback is paused, %FALSE otherwise
**/
gboolean
totem_is_paused (Totem *totem)
{
......
......@@ -34,8 +34,6 @@ G_BEGIN_DECLS
void totem_setup_preferences (Totem *totem);
void totem_preferences_visuals_setup (Totem *totem);
GtkWidget * bacon_cd_selection_create (void);
G_END_DECLS
#endif /* TOTEM_PREFERENCES_H */
......@@ -33,6 +33,11 @@
#include <totem-disc.h>
#include "totem-playlist.h"
/**
* TOTEM_GCONF_PREFIX:
*
* The GConf prefix under which all Totem GConf keys are stored.
**/
#define TOTEM_GCONF_PREFIX "/apps/totem"
G_BEGIN_DECLS
......@@ -103,6 +108,13 @@ typedef enum {
TOTEM_REMOTE_COMMAND_TOGGLE_ASPECT
} TotemRemoteCommand;
/**
* TotemRemoteSetting:
* @TOTEM_REMOTE_SETTING_SHUFFLE: whether shuffle is enabled
* @TOTEM_REMOTE_SETTING_REPEAT: whether repeat is enabled
*
* Represents a boolean setting or preference on a remote Totem instance.
**/
typedef enum {
TOTEM_REMOTE_SETTING_SHUFFLE,
TOTEM_REMOTE_SETTING_REPEAT
......@@ -124,6 +136,12 @@ GQuark totem_disc_media_type_quark (void);
#define TOTEM_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE (obj, totem_object_get_type ()))
#define TOTEM_IS_OBJECT_CLASS(klass) (G_CHECK_INSTANCE_GET_CLASS ((klass), totem_object_get_type ()))
/**
* Totem:
*
* The #Totem object is a handy synonym for #TotemObject, and the two can be used interchangably.
**/
/**
* TotemObject:
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment