ACCESS Developer Network | Using Media Selector User Interface

This chapter provides an overview of the interfaces to Media Selector, the widget-based graphical user interface for end users.

Overview ^TOP^

The Media Selector Service provides a convenient mechanism for applications to display information about media files and their uses, and to retrieve file selections. The Media Selector service makes file handling easier through search and sort functionality tuned by input from the user. The Media Selector widgets make this accessible to applications that handle media files.

Applications can call the Media Selector widget or Media Selector dialog to select content such as pictures, music, ringers, and other documents from both internal and external storage devices. ACCESS Linux Platform applications such as Picture Viewer, Audio, Camera Video and others, use the Media Selector UI.

Architecture and Components ^TOP^

The Media Selector service has a separate API available to create widgets to list the media files stored on the device or storage cards.

MediaSelector provides two widgets:

AlpMediaSelector Widget, which inherits from a GtkVbox, can be deployed within any UI to display file lists and retrieve a user selection.
AlpMediaSelector Dialog, which inherits from a GtkDialog, provides much the same interface as MediaSelectorWidget, but can incorporate dialog elements and buttons:

Applications can use the alp_media_selector_get_selections (for mediaselector) or the alp_media_selector_dialog_get_selections (for mediaselectordlg) functions at any time by using either widget or dialog to get the list of selections. (Currently, only a single selection is supported.) The application that called the widget is responsible for freeing the memory allocated for gchar**.

MediaSelector widgets support the following signals:

selection_changed, called whenever there is a new selection.
selection_activated, called whenever a selection is activated.

You can also retrieve media from MediaSelector using Exchange Manager. Use ExchangeMgr with the verb ALP_EXGMGR_GET_VERB and the mimetype (or supertype) specified (for example, "*", "audio/*", "image/jpg"). See ACCESS Linux Platform Applications Programming for more information about Exchange Manager. Use the alp_catalog -m command to list the known mimetypes. See "The alp_catalog Tool" for more information about alp_catalog.

AlpMediaSelector ^TOP^

The alp_mediaselector widget allows displaying, sorting, and selecting files on the device and storage cards.

Figure 4.1

Media Selector Widget example

The current uncustomized Media Selector GUI presents four predefined columns: icon, filename, size, icon.

It also displays a handful of categories with special information (for example, title instead of filename for audio/video/picture, or the number of items for collections). See "Searching with Media Selector" for more information about these categories and their information.

AlpMediaSelector Functions ^TOP^

Reference information is located in the Doxygen "User Interfaces:UI Widgets" Module and the /usr/include/alp/mediaselector.h File Reference. The following functions are defined for the API:

alp_media_selector_new Function ^TOP^

Purpose

Creates a new AlpMediaSelector widget.

Prototype

GtkWidget*  alp_media_selector_new(
   void
);

alp_media_selector_get_selections Function ^TOP^

Purpose

Get list of current selections.

Prototype

gchar**     alp_media_selector_get_selections(
    AlpMediaSelector* ms
);

The following displays the simple Media Selector widget:

AlpMediaSelectorDialog ^TOP^

The alp_mediaselectordlg dialog is a convenience widget which provides a container dialog for the AlpMediaSelector widget, and allow additional items, such as buttons, in the dialog box.

Figure 4.2

Media Selector Dialog example

AlpMediaSelectorDlg Functions ^TOP^

Reference information is located in "User Interfaces:UI Widgets" Module and /usr/include/alp/mediaselectordlg.h File Reference. The following functions are defined for the API:

alp_media_selector_dialog_new_with_buttons Function ^TOP^

Purpose :

Creates a new AlpMediaSelectorDialog.

Prototype

GtkWidget*  alp_media_selector_dialog_new_with_buttons(
   const gchar *title,
   GtkWindow *parent,
   GtkDialogFlags flags,
   const gchar *first_button_text,
   ...
);

alp_media_selector_dialog_new_with_buttons_valist Function ^TOP^

Purpose

Creates a new AlpMediaSelectorDialog (va_list version).

Prototype

GtkWidget*  alp_media_selector_dialog_new_with_buttons_valist(
   const gchar *title,
   GtkWindow *parent,
   GtkDialogFlags flags,
   const gchar *first_button_text,
   va_list valist
);

alp_media_selector_dialog_get_selections Function ^TOP^

Purpose

Get list of current selections.

Prototype

gchar** alp_media_selector_dialog_get_selections(
   AlpMediaSelectorDialog* dialog
);

The following displays a Media Selector Dialog, with a cancel button added:

Media Selector Dialog Graphic

Sample Application Using Media Selector ^TOP^

When you develop applications through which your end user selects files, the Media Selector UI provides you a mechanism to present files based on attributes.

You can use the Glade tool to create a custom widget. The following example code uses MediaSelector/MediaSelectorDialog with the "custom widget" feature of Glade.

To create a media selector widget using Glade, fill out the "Creation Function" in the "General Properties" tab of the custom widget.

Glade creates the MediaSelector ready to use. The user must define the on_*() functions.

Check the call to the gtk_widget_show_all function to be sure your widget is created and displayed.

Figure 4.3

Glade widget creation example

The following is the corresponding code from Glade.

// This is called automatically by Glade... 
GtkWidget* createMediaSelector(const char* str1, const char* str2, int a, int 
b) 
{    
    GtkWidget* mediaselector = alp_media_selector_new(); 
    g_object_set(G_OBJECT(mediaselector), ALP_MS_PROP_SORTBY, 
ALP_MS_SORTBY_NAME, NULL); 
    g_object_set(G_OBJECT(mediaselector), ALP_MS_PROP_SORT_ASCENDING, true, 
NULL); 
g_object_set(G_OBJECT(mediaselector), ALP_MS_PROP_VIEW_MODE, ALP_MS_VIEW_SINGLE 
NULL); 
    g_object_set(G_OBJECT(mediaselector), ALP_MS_PROP_CATEGORY, 
ALP_MS_CATEGORY_ALL, NULL); 
    g_signal_connect(G_OBJECT(mediaselector),  
        ALP_MS_SIGNAL_SELECTION_CHANGED, 
        G_CALLBACK (on_media_selector_selection_changed), 
        NULL); 
    g_signal_connect(G_OBJECT(mediaselector), 
        ALP_MS_SIGNAL_SELECTION_ACTIVATED, 
        G_CALLBACK(on_media_selector_selection_activate), 
        NULL); 
    gtk_widget_show_all(mediaselector); 
    return mediaselector; 
}