		libmplayer - The Media Player GUI Library
		=========================================
		    v0.6.0 - 12.03.2001 - Arthur Kleer

This file is part of the LinuX MultiMedia Project. It describes
the API of libmplayer. It is NOT complete and it is NOT describing
the final API ( probably ).

1. Introduction
===============

libmplayer provides the theme/skin code for LinuX Media Player. It also
can be used by Plugins to provide control panels. libmplayer is based
on Gtk and provides functions needed to create skinned windows of
XMMP type. The widgets are mainly the ones used by XMMS to provide
a similar GUI. However, it is not possible to use XMMS/Winamp skins,
as Wimamp compatible skins are stored really strange. There is no
system, for data organization in the pixmap. The positions are stored
in the program sourcecode. The Winamp compatibility has been removed,
to get a freely designable theme system.

2. General
==========

    2.1. Headers
    ------------
	mplayer.h is the only files that needs to be included.
	This also includes mplayertypes.h ( basic types ),
	mplayerwidgets.h ( the widget types and functions ) and
	support.h ( provides three Gtk support functions, created
	by glade )

    2.2. Basic data types
    ---------------------
	mptWidget is common to all widget types. Each of them
	contains this data type.

	mptTheme describes a theme. You need to initialize some
	fields before loading a theme. For example, you have
	to specify a array of mptWidgetEntry. Each entry describes
	one widget. Entry 0 MUST be the background. Entry 1 MUST
	be the widget you are using to move the window ( eg. titlebar )

    2.3. Events
    -----------
	You have to specify a event callback in you mptTheme object.
	This function will be called when one of the following events occur:

	MPLAYER_EVENT_FOCUS_IN
	MPLAYER_EVENT_FOCUS_OUT
	MPLAYER_EVENT_BUTTON_PRESS
	MPLAYER_EVENT_BUTTON_RELEASE
	MPLAYER_EVENT_MOTION
	MPLAYER_EVENT_THEMECHANGE

	You can use focus in and focus out to change the look of your
	application. The other events are handled my libmplayer, they
	are used to move your windows. However you can perform some
	aditional actions.

    2.4. Functions
    --------------

	> int mplayer_LoadTheme( char *theme, char *skin, mptTheme *tdesc );
	Load theme / skin. The structure of the theme is specified by dtesc.

	> void mplayer_FreeTheme( mptTheme *tdesc );
	Free theme.

	> void mplayer_InitTheme( mptTheme *tdesc, int state );
	This function has to be called after loading.
	( state = 1 theme should be double size )

	> int mplayer_ReloadDock( char *theme, char *skin );
	Load a new theme. The structure has to be the same as used
	int mplayer_LoadTheme()

	> void mplayer_WidgetDrawAll( mptTheme *tdesc );
	Redraw complete window.

	> void mplayer_WidgetVisible( void *w, int state );
	Toggle visibility of Widget 'w'

	> void mplayer_ShowWindow( mptTheme *theme );
	Show window.

	> void mplayer_HideWindow( mptTheme *theme );
	Hide window.

    2.5. Dialogues
    --------------
	libmplayer provides some standard dialogues, that can be used
	by applications.

	> void mplayer_Message( char *label, char *text );
	Display a window containing 'text' and as title 'label'

	> void mplayer_FileSelect( int mode, char *path, void (*_LoadDialogCallback)( char *filename, int mode ));
	Filebrowser. You have to provide a LoadDialogCallback function.

	> void mplayer_DirSelect( int mode, void (*_LoadDialogCallback)( char *path, int mode ));
	Select a directory.

	> void mplayer_UrlSelect( GList *url_history, void (*_LoadDialogCallback)( char *url ));
	Enter URL.

	> void mplayer_SkinBrowser( void );
	Browse the system and home directory for themes.

3. Widgets
==========

    Widget structure names start with mps ( eg. mpsList ), the type names
    start with mpt. To declare a Widget variable, you can use
    'struct mpsXXX' or 'mptXXX'.
    Functions manupulation widgets have mpw at the beginning of their name.

    3.1. Draw Area
    --------------

	Name:		mptDrawArea

	Description:	This Widget is used, when a application wants an area
			for painting some stuff into it.

	Functions:

	> void mpwDrawAreaSetData( mptDrawArea *da, unsigned char *idxdata );
	Is used to refresh the content of the area.


    3.2. List
    ---------
	
	Name:		mptList

	Description:	Scrollable list. You can select an item and move
			items to another position in the list

	Definitios:	MPLAYER_LIST_DOUBLE_CLICK
			Will be returned as argument to callback, when
			doubleclick event ocured.

	Functions:

	> int mpwListAddEntry( wList *list, char *text );
	Append entry to the list

	> void mpwListClear( wList *list );
	Remove all list elements

	> void mpwListSetActive( wList *list, int active );
	Set active list element

	> void mpwListRemove( wList *list, int num );
	Remove list element num

	> int mpwListSelectionGet( wList *list, int nth );
	Get selection state of elemt nth

	> int mpwListSelectionSet( wList *list, int nth, int flag );
	Set selection state of elemt nth


    3.3. Menu
    ---------
	
	Name:		mptMenu

	Description:	Simple Menu. Only a menubar without popups.


    3.4. Number
    -----------
	
	Name:		mptNumber

	Description:	Widget containing a number with a specified number
			of digits.

	Functions:

	> void mpwNumberSetValue( wNumber *num, int value );
	Set the number that should be drawn to the widget.

    3.5. Push button
    ----------------
	
	Name:		mptPushButton

	Description:	Pushbuttpon widget ( eg. play button )


    3.6. Toggle Button
    ------------------
	
	Name:		mptToggleButton

	Description:	ToggleButton widget ( eg. repeat button )

	Functions:

	> int mpwToggleButtonState( wToggleButton *tb, int state );
	Set state of the button ( 1 = pushed )


    3.7. Pixmap
    -----------

	Name:		mptPixmap

	Description:	A pixmap. ( used for the background )


    3.8. Popup
    ----------
	
	Name:		mptPopup

	Description:	Popup menu. Pushing the button will popup a menu.


    3.9. Slider
    -----------

	Name:		mptSlider

	Description:	Slider. ( eg. volume control bar )

	Functions:

	> int mpwSliderSetValue( wSlider *hs, int value );
	Set slider value ( range: 0 - 100 )


    3.10. Status
    ------------
	
	Name:		mptStatus

	Description:	Widget containing a status

	Functions:

	> int wStatusSetStatus( wStatus *st, int status );
	Set state of status widget

	> int wStatusGetStatus( wStatus *st );
	Get state of status widget


    3.11. Textbox
    -------------
	
	Name:		mptTextBox

	Description:	A textbox may contaion any string

	Functions:

	> int wTextBoxSetText( wTextBox *tb, char *text );
	Set content that will be shown in the textbox.


4. Theme description file
=========================
