SwfdecPlayer
3
SWFDEC Library

# SwfdecPlayer

main playback object

## Synopsis

    #include <swfdec/swfdec.h>

                        SwfdecPlayer;
    void                swfdec_init                         (void);
    SwfdecPlayer*       swfdec_player_new                   (SwfdecAsDebugger *debugger);
    gboolean            swfdec_player_is_initialized        (SwfdecPlayer *player);
    const SwfdecURL*    swfdec_player_get_url               (SwfdecPlayer *player);
    void                swfdec_player_set_url               (SwfdecPlayer *player,
                                                             const SwfdecURL *url);
    const SwfdecURL*    swfdec_player_get_base_url          (SwfdecPlayer *player);
    void                swfdec_player_set_base_url          (SwfdecPlayer *player,
                                                             const SwfdecURL *url);
    const char*         swfdec_player_get_variables         (SwfdecPlayer *player);
    void                swfdec_player_set_variables         (SwfdecPlayer *player,
                                                             const char *variables);
    double              swfdec_player_get_rate              (SwfdecPlayer *player);
    void                swfdec_player_get_default_size      (SwfdecPlayer *player,
                                                             guint *width,
                                                             guint *height);
    void                swfdec_player_get_size              (SwfdecPlayer *player,
                                                             int *width,
                                                             int *height);
    void                swfdec_player_set_size              (SwfdecPlayer *player,
                                                             int width,
                                                             int height);
    glong               swfdec_player_get_next_event        (SwfdecPlayer *player);
    guint               swfdec_player_get_background_color  (SwfdecPlayer *player);
    void                swfdec_player_set_background_color  (SwfdecPlayer *player,
                                                             guint color);
    SwfdecScaleMode     swfdec_player_get_scale_mode        (SwfdecPlayer *player);
    void                swfdec_player_set_scale_mode        (SwfdecPlayer *player,
                                                             SwfdecScaleMode mode);
    SwfdecAlignment     swfdec_player_get_alignment         (SwfdecPlayer *player);
    void                swfdec_player_set_alignment         (SwfdecPlayer *player,
                                                             SwfdecAlignment align);
    SwfdecPlayerScripting* swfdec_player_get_scripting      (SwfdecPlayer *player);
    void                swfdec_player_set_scripting         (SwfdecPlayer *player,
                                                             SwfdecPlayerScripting *scripting);
    void                swfdec_player_render                (SwfdecPlayer *player,
                                                             cairo_t *cr,
                                                             double x,
                                                             double y,
                                                             double width,
                                                             double height);
    gulong              swfdec_player_advance               (SwfdecPlayer *player,
                                                             gulong msecs);
    gboolean            swfdec_player_mouse_move            (SwfdecPlayer *player,
                                                             double x,
                                                             double y);
    gboolean            swfdec_player_mouse_press           (SwfdecPlayer *player,
                                                             double x,
                                                             double y,
                                                             guint button);
    gboolean            swfdec_player_mouse_release         (SwfdecPlayer *player,
                                                             double x,
                                                             double y,
                                                             guint button);
    gboolean            swfdec_player_key_press             (SwfdecPlayer *player,
                                                             guint keycode,
                                                             guint character);
    gboolean            swfdec_player_key_release           (SwfdecPlayer *player,
                                                             guint keycode,
                                                             guint character);
    void                swfdec_player_render_audio          (SwfdecPlayer *player,
                                                             gint16 *dest,
                                                             guint start_offset,
                                                             guint n_samples);
    const GList*        swfdec_player_get_audio             (SwfdecPlayer *player);
    gulong              swfdec_player_get_maximum_runtime   (SwfdecPlayer *player);
    void                swfdec_player_set_maximum_runtime   (SwfdecPlayer *player,
                                                             gulong msecs);

## Object Hierarchy

      GObject
       +----SwfdecAsContext
             +----SwfdecPlayer
                   +----SwfdecGtkPlayer

## Properties

      "alignment"                SwfdecAlignment       : Read / Write
      "background-color"         guint                 : Read / Write
      "base-url"                 SwfdecURL*            : Read / Write
      "cache-size"               gulong                : Read / Write
      "default-height"           guint                 : Read
      "default-width"            guint                 : Read
      "height"                   gint                  : Read / Write
      "initialized"              gboolean              : Read
      "loader-type"              GType*                : Read / Write / Construct Only
      "max-runtime"              gulong                : Read / Write
      "mouse-cursor"             SwfdecMouseCursor     : Read
      "next-event"               glong                 : Read
      "rate"                     gdouble               : Read
      "scale-mode"               SwfdecScaleMode       : Read / Write
      "scripting"                SwfdecPlayerScripting*  : Read / Write
      "socket-type"              GType*                : Read / Write / Construct Only
      "start-time"               SwfdecTimeVal*        : Write / Construct Only
      "system"                   SwfdecSystem*         : Read / Write
      "url"                      SwfdecURL*            : Read
      "variables"                gchar*                : Read / Write
      "width"                    gint                  : Read / Write

## Signals

      "advance"                                        : Run Last
      "audio-added"                                    : Run Last
      "audio-removed"                                  : Run Last
      "fscommand"                                      : Run Last
      "handle-key"                                     : Run Last
      "handle-mouse"                                   : Run Last
      "invalidate"                                     : Run Last
      "launch"                                         : Run Last
      "missing-plugins"                                : Run Last

## Description

A SwfdecPlayer is the main object used for playing back Flash files through Swfdec.

A player interacts with the outside world in a multitude of ways. The most important ones are described below.

Input is handled via the SwfdecLoader class. A SwfdecLoader is set on a new player using `swfdec_player_set_loader()`.

When the loader has provided enough data, you can start playing the file. This is done in steps by calling `swfdec_player_advance()` - preferrably as often as `swfdec_player_get_next_event()` indicates. Or you can provide user input to the player by calling for example `swfdec_player_handle_mouse()`.

You can use `swfdec_player_render()` to draw the current state of the player. After that, connect to the SwfdecPlayer::invalidate signal to be notified of changes.

Audio output is handled via the SwfdecAudio class. One SwfdecAudio object is created for every output using the SwfdecPlayer::audio-added signal.

## Details

### 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.

`debugger` :

  `NULL` or a SwfdecAsDebugger to use for debugging this player.

Returns :

  The new player

### 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.

`player` :

  a SwfdecPlayer

Returns :

  TRUE if the basic values are known.

### 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.

`player` :

  a SwfdecPlayer

Returns :

  the SwfdecURL currently played back or `NULL`

### 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.

`player` :

  a SwfdecPlayer

`url` :

  the url for the initial reference in this player

### 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.

`player` :

  a SwfdecPlayer

Returns :

  the base SwfdecURL for resolving relative links or `NULL`

### 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`.

`player` :

  a SwfdecPlayer

`url` :

  a SwfdecURL or `NULL` to reset to defaults

### 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.

`player` :

  a SwfdecPlayer

Returns :

  a string represetation of the current variables or `NULL` if none are set on the `player`.

### 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.

`player` :

  a SwfdecPlayer

`variables` :

  a string that is checked to be in 'application/x-www-form-urlencoded' syntax describing the arguments to set on the new player or NULL for none.

### 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. It is possible that the movie has no framerate if it does not display a Flash movie but an FLV video for example. This does not mean it will not change however.

`player` :

  a SwfdecPlayer

Returns :

  The framerate of this movie or 0 if it isn't known yet or the movie doesn't have a framerate.

### 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.

`player` :

  a SwfdecPlayer

`width` :

  integer to store the width in or `NULL`

`height` :

  integer to store the height in or `NULL`

### 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.

`player` :

  a SwfdecPlayer

`width` :

  integer to store the width in or `NULL`

`height` :

  integer to store the height in or `NULL`

### 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.

`player` :

  a SwfdecPlayer

`width` :

  desired width of the movie or -1 for default

`height` :

  desired height of the movie or -1 for default

### 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.

`player` :

  ia SwfdecPlayer

Returns :

  number of milliseconds until next event or -1 if no outstanding event

### swfdec_player_get_background_color ()

    guint               swfdec_player_get_background_color  (SwfdecPlayer *player);

Gets the current background color. The color will be an ARGB-quad, with the MSB being the alpha value.

`player` :

  a SwfdecPlayer

Returns :

  the background color as an ARGB value

### swfdec_player_set_background_color ()

    void                swfdec_player_set_background_color  (SwfdecPlayer *player,
                                                             guint color);

Sets a new background color as an ARGB value. To get transparency, set the value to 0. To get a black beackground, use 0xFF000000.

`player` :

  a SwfdecPlayer

`color` :

  new color to use as background 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.

`player` :

  a SwfdecPlayer

Returns :

  the current scale mode

### 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.

`player` :

  a SwfdecPlayer

`mode` :

  a SwfdecScaleMode

### 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.

`player` :

  a SwfdecPlayer

Returns :

  the current alignment

### 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.

`player` :

  a SwfdecPlayer

`align` :

  SwfdecAlignment to set

### 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.

`player` :

  a SwfdecPlayer

Returns :

  the current scripting implementation used or `NULL` if none

### 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.

`player` :

  a SwfdecPlayer

`scripting` :

  the scripting implementation to use or `NULL` to disable scripting

### swfdec_player_render ()

    void                swfdec_player_render                (SwfdecPlayer *player,
                                                             cairo_t *cr,
                                                             double x,
                                                             double y,
                                                             double width,
                                                             double height);

Renders the given area of the current frame to `cr`.

`player` :

  a SwfdecPlayer

`cr` :

  cairo_t to render to

`x` :

  x coordinate of top left position to render

`y` :

  y coordinate of top left position to render

`width` :

  width of area to render or 0 for full width

`height` :

  height of area to render or 0 for full height

### 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.

`player` :

  the SwfdecPlayer to advance

`msecs` :

  number of milliseconds to advance at maximum

Returns :

  actual number of milliseconds advanced.

### 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.

`player` :

  a SwfdecPlayer

`x` :

  x coordinate of mouse

`y` :

  y coordinate of mouse

Returns :

  `TRUE` if the mouse event was handled. `FALSE` if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

### 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.

`player` :

  a SwfdecPlayer

`x` :

  x coordinate of mouse

`y` :

  y coordinate of mouse

`button` :

  number of the button that was pressed. Swfdec supports up to 32 buttons.

Returns :

  `TRUE` if the mouse event was handled. `FALSE` if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

### 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.

`player` :

  a SwfdecPlayer

`x` :

  x coordinate of mouse

`y` :

  y coordinate of mouse

`button` :

  number of the button that was released. Swfdec supports up to 32 buttons.

Returns :

  `TRUE` if the mouse event was handled. `FALSE` if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

### 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.

`player` :

  a SwfdecPlayer

`keycode` :

  the key that was pressed, must be smaller than 256.

`character` :

  UCS4 of the character that was inserted or 0 if none

Returns :

  `TRUE` if the key press was handled by the `player`, `FALSE` if it should be propagated further

### 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.

`player` :

  a SwfdecPlayer

`keycode` :

  the key that was released

`character` :

  UCS4 of the character that was inserted or 0 if none

Returns :

  `TRUE` if the key press was handled by the `player`, `FALSE` if it should be propagated further

### swfdec_player_render_audio ()

    void                swfdec_player_render_audio          (SwfdecPlayer *player,
                                                             gint16 *dest,
                                                             guint start_offset,
                                                             guint n_samples);

Renders the data for this frame into the given location. The data is added to `dest`, so you probably want to initialize `dest` to silence before calling this function.

`player` :

  a SwfdecPlayer

`dest` :

  location to add audio signal to. The audio signal will be in 44100kHz signed 16bit stereo.

`start_offset` :

  offset in samples at which to start rendering. The offset is calculated relative to the last iteration, so the value set by `swfdec_player_set_audio_advance()` is ignored.

`n_samples` :

  amount of samples to render.

### swfdec_player_get_audio ()

    const GList*        swfdec_player_get_audio             (SwfdecPlayer *player);

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

`player` :

  a SwfdecPlayer

Returns :

  A GList of SwfdecAudio. You must not modify or free this list.

### 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.

`player` :

  a SwfdecPlayer

Returns :

  the maximum time in milliseconds that scripts are allowed to run or 0 for infinite.

### 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.

`player` :

  a SwfdecPlayer

`msecs` :

  time in milliseconds that scripts are allowed to run or 0 for infinite

## Property Details

### The `"alignment"` property

      "alignment"                SwfdecAlignment       : Read / Write

point of the screen to align the output to.

Default value: SWFDEC_ALIGNMENT_CENTER

### The `"background-color"` property

      "background-color"         guint                 : Read / Write

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 `"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 `"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 `"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

## Signal Details

### The `"advance"` signal

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

Emitted whenever the player advances.

`player` :

  the SwfdecPlayer affected

`msecs` :

  the amount of milliseconds the player will advance

`audio_samples` :

  number of frames the audio is advanced (in 44100Hz steps)

`user_data` :

  user data set when the signal handler was connected.

### 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`.

`player` :

  the SwfdecPlayer affected

`audio` :

  the audio stream that was added

`user_data` :

  user data set when the signal handler was connected.

### 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.

`player` :

  the SwfdecPlayer affected

`audio` :

  the audio stream that was removed

`user_data` :

  user data set when the signal handler was connected.

### 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:

- "quit": quits the player.

- "fullscreen": A boolean setting (parameter is "true" or "false") that sets the player into fullscreen mode.

- "allowscale": A boolean setting that tells the player to not scale the Flash application.

- "showmenu": A boolean setting that tells the Flash player to not show its own entries in the right-click menu.

- "exec": Run an external executable. The parameter specifies the path.

- "trapallkeys": A boolean setting that tells the Flash player to pass all key events to the Flash application instead of using it for keyboard shortcuts or similar.

`player` :

  the SwfdecPlayer affected

`command` :

  the command to execute. This is a lower case string.

`parameter` :

  parameter to pass to the command. The parameter depends on the function.

`user_data` :

  user data set when the signal handler was connected.

### 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.

`player` :

  the SwfdecPlayer affected

`key` :

  SwfdecKey that was pressed or released

`pressed` :

  `TRUE` if the `key` was pressed or `FALSE` if it was released

`user_data` :

  user data set when the signal handler was connected.

Returns :

  TRUE if this handler handles the event.

### 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.

`player` :

  the SwfdecPlayer affected

`x` :

  new x coordinate of the mouse

`y` :

  new y coordinate of the mouse

`button` :

  0 for a mouse move, a positive number if a button was pressed, a negative number if a button was released

`user_data` :

  user data set when the signal handler was connected.

Returns :

  TRUE if this handler handles the event.

### The `"invalidate"` signal

    void                user_function                      (SwfdecPlayer    *player,
                                                            SwfdecRectangle *extents,
                                                            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.

`player` :

  the SwfdecPlayer affected

`extents` :

  the smallest rectangle enclosing the full region of changes

`rectangles` :

  a number of smaller rectangles for fine-grained control over changes

`n_rectangles` :

  number of rectangles in `rectangles`

`user_data` :

  user data set when the signal handler was connected.

### The `"launch"` signal

    void                user_function                      (SwfdecPlayer       *player,
                                                            SwfdecLoaderRequest request,
                                                            gchar              *url,
                                                            gchar              *target,
                                                            SwfdecBuffer       *data,
                                                            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.

`player` :

  the SwfdecPlayer affected

`request` :

  the type of request

`url` :

  URL to open

`target` :

  target to load the URL into

`data` :

  optional data to pass on with the request. Will be of mime type application/x-www-form-urlencoded. Can be `NULL` indicating no data should be passed.

`user_data` :

  user data set when the signal handler was connected.

### The `"missing-plugins"` signal

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

`player` :

  the SwfdecPlayer missing plugins

`details` :

  the details strigs for all missing plugins

`user_data` :

  user data set when the signal handler was connected.