SwfdecPlayer

typedef struct _SwfdecPlayer SwfdecPlayer;

This is the base object used for playing Flash files.

swfdec_init ()

void                swfdec_init                         (void);

Initializes the Swfdec library.

swfdec_player_new ()

SwfdecPlayer*       swfdec_player_new                   (SwfdecAsDebugger *debugger);

Creates a new player. This function is supposed to be used for testing. Because of this, the created player will behave as predictable as possible. For example, it will generate the same random number sequence every time. The function calls swfdec_init() for you if it wasn't called before.

swfdec_player_is_initialized ()

gboolean            swfdec_player_is_initialized        (SwfdecPlayer *player);

Determines if the player is initalized yet. An initialized player is able to provide basic values like width, height or rate. A player may not be initialized if the loader it was started with does not reference a Flash resources or it did not provide enough data yet. If a player is initialized, it will never be uninitialized again.

swfdec_player_get_url ()

const SwfdecURL*    swfdec_player_get_url               (SwfdecPlayer *player);

Gets the URL of the resource that is currently played back. If no URL has been set on the player yet, NULL is returned.

swfdec_player_set_url ()

void                swfdec_player_set_url               (SwfdecPlayer *player,
                                                         const SwfdecURL *url);

Sets the url for the main data. This function may only be called once.

swfdec_player_get_base_url ()

const SwfdecURL*    swfdec_player_get_base_url          (SwfdecPlayer *player);

Gets the base URL that this player uses when resolving a relative URL. It is automatically set to the parent directory of the currently played back resource, but can be changed using swfdec_player_set_base_url(). When no resource has been set on the player yet, NULL is returned.

swfdec_player_set_base_url ()

void                swfdec_player_set_base_url          (SwfdecPlayer *player,
                                                         const SwfdecURL *url);

Sets the URL that will be used for resolving realtive links inside the player.

swfdec_player_get_variables ()

const char*         swfdec_player_get_variables         (SwfdecPlayer *player);

Gets the initial variables for this player. See swfdec_player_set_variables() for details about variables.

swfdec_player_set_variables ()

void                swfdec_player_set_variables         (SwfdecPlayer *player,
                                                         const char *variables);

Sets the loader for the main data. This function may only be called if swfdec_player_set_url() has not been called yet. If the variables are set and validate, they will be set as properties on the root movie.

swfdec_player_get_rate ()

double              swfdec_player_get_rate              (SwfdecPlayer *player);

Queries the framerate of this movie. This number specifies the number of frames that are supposed to pass per second. It is a multiple of 1/256.

swfdec_player_get_default_size ()

void                swfdec_player_get_default_size      (SwfdecPlayer *player,
                                                         guint *width,
                                                         guint *height);

If the default size of the movie is initialized, fills in width and height with the size. Otherwise width and height are set to 0.

swfdec_player_get_size ()

void                swfdec_player_get_size              (SwfdecPlayer *player,
                                                         int *width,
                                                         int *height);

Gets the currently set image size. If the default width or height should be used, the width or height respectively is set to -1.

swfdec_player_set_size ()

void                swfdec_player_set_size              (SwfdecPlayer *player,
                                                         int width,
                                                         int height);

Sets the image size to the given values. The image size is what the area that the player will render and advocate with scripts.

swfdec_player_get_next_event ()

glong               swfdec_player_get_next_event        (SwfdecPlayer *player);

Queries how long to the next event. This is the next time when you should call swfdec_player_advance() to forward to.

swfdec_player_get_background_color ()

guint               swfdec_player_get_background_color  (SwfdecPlayer *player);

Gets the current suggested background color. The color will be an ARGB-color, with the MSB being the alpha value. Note that Swfdec will not render the background color itself, so if you want the background to not be translucent it is your job to clear the background using this color.

swfdec_player_get_scale_mode ()

SwfdecScaleMode     swfdec_player_get_scale_mode        (SwfdecPlayer *player);

Gets the currrent mode used for scaling the movie. See SwfdecScaleMode for the different modes.

swfdec_player_set_scale_mode ()

void                swfdec_player_set_scale_mode        (SwfdecPlayer *player,
                                                         SwfdecScaleMode mode);

Sets the currrent mode used for scaling the movie. See SwfdecScaleMode for the different modes.

swfdec_player_get_alignment ()

SwfdecAlignment     swfdec_player_get_alignment         (SwfdecPlayer *player);

Gets the alignment of the player. The alignment describes what point is used as the anchor for drawing the contents. See SwfdecAlignment for possible values.

swfdec_player_set_alignment ()

void                swfdec_player_set_alignment         (SwfdecPlayer *player,
                                                         SwfdecAlignment align);

Sets the alignment to align. For details about alignment, see swfdec_player_get_alignment() and SwfdecAlignment.

swfdec_player_get_scripting ()

SwfdecPlayerScripting* swfdec_player_get_scripting      (SwfdecPlayer *player);

Gets the current scripting implementation in use. If no implementation is in use (the default), NULL is returned.

swfdec_player_set_scripting ()

void                swfdec_player_set_scripting         (SwfdecPlayer *player,
                                                         SwfdecPlayerScripting *scripting);

Sets the implementation to use for external scripting in the given player. Note that this is different from the internal script engine. See the SwfdecPlayerScripting paragraph for details about external scripting.

swfdec_player_get_allow_fullscreen ()

gboolean            swfdec_player_get_allow_fullscreen  (SwfdecPlayer *player);

Checks if the player is allowed to go fullscreen. See swfdec_player_set_allow_fullscreen() for details.

swfdec_player_set_allow_fullscreen ()

void                swfdec_player_set_allow_fullscreen  (SwfdecPlayer *player,
                                                         gboolean allow);

Sets if the player is allowed to go fullscreen. If a player is allowed to go fullscreen, it may set the SwfdecPlayer::fullscreen property to TRUE. Players are not allowed to go fullscreen by default. Usually applications only want to allow going fullscreen in response to mouse or keyboard events.

swfdec_player_get_fullscreen ()

gboolean            swfdec_player_get_fullscreen        (SwfdecPlayer *player);

CHecks if the player is in fullscreen mode currently. If the player is in fullscreen mode, it assumes it occupies the whole screen. A player will only ever go into fullscreen, if you have allowed it by calling swfdec_player_set_allow_fullscreen().

swfdec_player_get_renderer ()

SwfdecRenderer*     swfdec_player_get_renderer          (SwfdecPlayer *player);

Gets the current renderer in use. See swfdec_player_set_renderer() for details.

swfdec_player_set_renderer ()

void                swfdec_player_set_renderer          (SwfdecPlayer *player,
                                                         SwfdecRenderer *renderer);

Sets the renderer to be used by the player. Setting the correct renderer is mostly relevant for TextField flash objects with native fonts, as the renderer provides those. It can also be very relevant for performance reasons. See the SwfdecRenderer documentation for details.

swfdec_player_render ()

void                swfdec_player_render                (SwfdecPlayer *player,
                                                         cairo_t *cr);

Renders the given area of the current frame to cr. This function just calls swfdec_player_render_with_renderer() using the player's renderer.

swfdec_player_render_with_renderer ()

void                swfdec_player_render_with_renderer  (SwfdecPlayer *player,
                                                         cairo_t *cr,
                                                         SwfdecRenderer *renderer);

Renders the given area of the current frame to cr. If you only want to redraw parts of the player, like when responding to a SwfdecPlayer:invalidate signal, set a clip on cr using cairo_clip():

cairo_rectangle (cr, x, y, width, height);
cairo_clip (cr);
swfdec_player_render_with_renderer (player, cr, renderer);

Only redrawing parts of the player improves performance considerably.

swfdec_player_advance ()

gulong              swfdec_player_advance               (SwfdecPlayer *player,
                                                         gulong msecs);

Advances player by msecs or at most one event, whatever happens first in the player's timeline. You should make sure to call this function as often as swfdec_player_get_next_event() indicates or your player will not appear smooth.

swfdec_player_mouse_move ()

gboolean            swfdec_player_mouse_move            (SwfdecPlayer *player,
                                                         double x,
                                                         double y);

Updates the current mouse position. If the mouse has left the area of player, you should pass values outside the movie size for x and y. You will probably want to call swfdec_player_advance() before to update the player to the correct time when calling this function.

swfdec_player_mouse_press ()

gboolean            swfdec_player_mouse_press           (SwfdecPlayer *player,
                                                         double x,
                                                         double y,
                                                         guint button);

Tells the player that the mouse button button was pressed at the given coordinate.

swfdec_player_mouse_release ()

gboolean            swfdec_player_mouse_release         (SwfdecPlayer *player,
                                                         double x,
                                                         double y,
                                                         guint button);

Tells the player that the mouse button button was released at the given coordinate.

swfdec_player_key_press ()

gboolean            swfdec_player_key_press             (SwfdecPlayer *player,
                                                         guint keycode,
                                                         guint character);

Call this function to make the player react to a key press. A list of defined key codes is defined by SwfdecKey. You will likely need to translate from your keyboard API to the Flash key codes.

swfdec_player_key_release ()

gboolean            swfdec_player_key_release           (SwfdecPlayer *player,
                                                         guint keycode,
                                                         guint character);

Call this function to make the player react to a key being released. See swfdec_player_key_press() for details.

swfdec_player_get_focus ()

gboolean            swfdec_player_get_focus             (SwfdecPlayer *player);

Checks if the player has keyboard focus. See swfdec_player_set_focus() for details.

swfdec_player_set_focus ()

void                swfdec_player_set_focus             (SwfdecPlayer *player,
                                                         gboolean focus);

Tells the player whether keyboard focus is inside it. The player will use this information to draw focus indicators around objects. Note that this update will not happen immediately, but only the next time you call swfdec_player_advance(). The player is focussed by default. So if you integrate it into a widget system such, you likely want to unset this upon creation of the player.

swfdec_player_get_selection ()

const char*         swfdec_player_get_selection         (SwfdecPlayer *player);

Retrieves the currently selected text of the player. If no text is currently selected, NULL is returned.

swfdec_player_get_audio ()

const GList*        swfdec_player_get_audio             (SwfdecPlayer *player);

Returns a list of all currently active audio streams in player.

swfdec_player_get_maximum_runtime ()

gulong              swfdec_player_get_maximum_runtime   (SwfdecPlayer *player);

Queries the given player for how long scripts may run. see swfdec_player_set_maximum_runtime() for a longer discussion of this value.

swfdec_player_set_maximum_runtime ()

void                swfdec_player_set_maximum_runtime   (SwfdecPlayer *player,
                                                         gulong msecs);

Sets the time that the player may use to let internal scripts run. If the Flash file that is currently played back does not manage to complete its scripts in the given time, it is aborted. You cannot continue the scripts at a later point in time. However, your application may become unresponsive and your users annoyed if they cannot interact with it for too long. To give a reference point, the Adobe Flash player usually sets this value to 10 seconds. Note that this time determines the maximum time calling swfdec_player_advance() may take, even if it is called with a large value. Also note that this setting is ignored when running inside a debugger.

The "alignment" property

  "alignment"                SwfdecAlignment       : Read / Write

point of the screen to align the output to.

Default value: SWFDEC_ALIGNMENT_CENTER

The "allow-fullscreen" property

  "allow-fullscreen"         gboolean              : Read / Write

if the player is allowed to change into fullscreen mode.

Default value: FALSE

The "background-color" property

  "background-color"         guint                 : Read

ARGB color used to draw the background.

Default value: 4294967295

The "base-url" property

  "base-url"                 SwfdecURL*            : Read / Write

base URL for creating new resource or NULL if not set yet.

The "cache-size" property

  "cache-size"               gulong                : Read / Write

maximum cache size in bytes.

The "default-height" property

  "default-height"           guint                 : Read

default height of the movie.

Default value: 0

The "default-width" property

  "default-width"            guint                 : Read

default width of the movie.

Default value: 0

The "focus" property

  "focus"                    gboolean              : Read / Write

TRUE if the player has keyboard focus.

Default value: TRUE

The "fullscreen" property

  "fullscreen"               gboolean              : Read

if the player is in fullscreen mode.

Default value: FALSE

The "height" property

  "height"                   gint                  : Read / Write

current height of the movie.

Allowed values: >= -1

Default value: -1

The "initialized" property

  "initialized"              gboolean              : Read

TRUE when the player has initialized its basic values.

Default value: FALSE

The "loader-type" property

  "loader-type"              GType*                : Read / Write / Construct Only

type to use for creating loaders.

The "max-runtime" property

  "max-runtime"              gulong                : Read / Write

maximum time in msecs scripts may run in the player before aborting.

The "mouse-cursor" property

  "mouse-cursor"             SwfdecMouseCursor     : Read

how the mouse pointer should be presented.

Default value: SWFDEC_MOUSE_CURSOR_NONE

The "next-event" property

  "next-event"               glong                 : Read

how many milliseconds until the next event or -1 when no event pending.

Allowed values: >= -1

Default value: -1

The "rate" property

  "rate"                     gdouble               : Read

rate in frames per second.

Allowed values: [0,256]

Default value: 0

The "renderer" property

  "renderer"                 SwfdecRenderer*       : Read / Write / Construct

the renderer used by this player.

The "scale-mode" property

  "scale-mode"               SwfdecScaleMode       : Read / Write

method used to scale the movie.

Default value: SWFDEC_SCALE_SHOW_ALL

The "scripting" property

  "scripting"                SwfdecPlayerScripting*  : Read / Write

external scripting implementation.

The "selection" property

  "selection"                gchar*                : Read

currently selected text.

Default value: NULL

The "socket-type" property

  "socket-type"              GType*                : Read / Write / Construct Only

type to use for creating sockets.

The "start-time" property

  "start-time"               SwfdecTimeVal*        : Write / Construct Only

time to use as the beginning time for this player.

The "system" property

  "system"                   SwfdecSystem*         : Read / Write

object holding system information.

The "url" property

  "url"                      SwfdecURL*            : Read

URL of resource currently played back or NULL if not set.

The "variables" property

  "variables"                gchar*                : Read / Write

variables to use when setting the URL.

Default value: NULL

The "width" property

  "width"                    gint                  : Read / Write

current width of the movie.

Allowed values: >= -1

Default value: -1

The "advance" signal

void                user_function                      (SwfdecPlayer *player,
                                                        gulong        msecs,
                                                        guint         audio_samples,
                                                        gpointer      user_data)          : Run Last

Emitted whenever the player advances.

The "audio-added" signal

void                user_function                      (SwfdecPlayer *player,
                                                        SwfdecAudio  *audio,
                                                        gpointer      user_data)      : Run Last

Emitted whenever a new audio stream was added to player.

The "audio-removed" signal

void                user_function                      (SwfdecPlayer *player,
                                                        SwfdecAudio  *audio,
                                                        gpointer      user_data)      : Run Last

Emitted whenever an audio stream was removed from player. The stream will have been added with the SwfdecPlayer::audio-added signal previously.

The "fscommand" signal

void                user_function                      (SwfdecPlayer *player,
                                                        gchar        *command,
                                                        gchar        *parameter,
                                                        gpointer      user_data)      : Run Last

This signal is emited whenever a Flash script command (also known as fscommand) is encountered. This method is ued by the Flash file to communicate with the hosting environment. In web browsers it is used to call Javascript functions. Standalone Flash players understand a limited set of functions. They vary from player to player, but the most common are listed here:

The "handle-key" signal

gboolean            user_function                      (SwfdecPlayer *player,
                                                        guint         key,
                                                        guint         pressed,
                                                        gboolean      Returns,
                                                        gpointer      user_data)      : Run Last

This signal is emitted whenever player should respond to a key event. If any of the handlers returns TRUE, swfdec_player_key_press() or swfdec_player_key_release() will return TRUE. Note that unlike many event handlers in gtk, returning TRUE will not stop further event handlers from being invoked. Use g_signal_stop_emission() in that case.

The "handle-mouse" signal

gboolean            user_function                      (SwfdecPlayer *player,
                                                        gdouble       x,
                                                        gdouble       y,
                                                        gint          button,
                                                        gpointer      user_data)      : Run Last

This signal is emitted whenever player should respond to a mouse event. If any of the handlers returns TRUE, swfdec_player_handle_mouse() will return TRUE. Note that unlike many event handlers in gtk, returning TRUE will not stop further event handlers from being invoked. Use g_signal_stop_emission() in that case.

The "invalidate" signal

void                user_function                      (SwfdecPlayer *player,
                                                        gpointer      rectangles,
                                                        guint         n_rectangles,
                                                        gpointer      user_data)         : Run Last

This signal is emitted whenever graphical elements inside the player have changed. It provides two ways to look at the changes: By looking at the extents parameter, it provides a simple way to get a single rectangle that encloses all changes. By looking at the rectangles array, you can get finer control over changes which is very useful if your rendering system provides a way to handle regions.

The "launch" signal

void                user_function                      (SwfdecPlayer *player,
                                                        gchar        *url,
                                                        gchar        *target,
                                                        SwfdecBuffer *data,
                                                        guint         header_count,
                                                        GStrv        *header_names,
                                                        GStrv        *header_values,
                                                        gpointer      user_data)          : Run Last

Emitted whenever the player encounters an URL that should be loaded into a target the Flash player does not recognize. In most cases this happens when the user clicks a link in an embedded Flash movie that should open a new web page. The effect of calling any swfdec functions on the emitting player is undefined.

The "missing-plugins" signal

void                user_function                      (SwfdecPlayer *player,
                                                        GStrv        *details,
                                                        gpointer      user_data)      : Run Last

Emitted whenever a plugin is detected that GStreamer cannot currently handle because it is missing plugins to do so. You should use gst_install_plugins_async() to install those plugins.

The "query-size" signal

gboolean            user_function                      (SwfdecPlayer *player,
                                                        gboolean      fullscreen,
                                                        gpointer      width,
                                                        gpointer      height,
                                                        gpointer      user_data)       : Run Last

This signals is emitted whenever the player is (un)fullscreened. In this case it requests the new size the Flash file will be displayed in immediately. If you want to provide values, connect to this signal. The values don't have to be exact, you can still call swfdec_player_set_size() later on. However, it will look visually nicer if your values here are correct. By default, the screen resolution values will be used for fullscreen and the default size will be used otherwise.