                        Gmp3 - A front-end to mpg123
                              by Brett Kosinski

Disclaimer
----------

I only put this in here for people thinking of hacking my code.  This is a
very ickily (that's right, ickily ;) written program.  I'm thinking down the
line it could very will be completely rewritten with a little more thought
put into design, but this is what I have so far.  Have fun with it! >:)


Introduction
------------

Well, I see you downloaded Gmp3 and are getting ready to check it out. 
Well, here is some information to get you started.

First of all, here are the requirements for Gmp3:

- The latest GTK (currently 1.0.0)
- GDK_Imlib 1.1+, preferably with built-in jpeg support.
- mpg123 0.59o
- An OSS or compatible sound card for use with the mixer (ie /dev/mixer
  device)

If you have all these things you should be set.  Note, an OSS compatible
sound blast is NOT required.  It's simply needed for the built-in mixer to
function.


The New Version
---------------

Well, with the release of 0.05, Gmp3 has changed substantially.  The first
thing for past users to realize is now Gmp3's configuration files are
located in $HOME/.gmp3 (unless this is changed).  This is where the RC file
is stored and any local themes the user wishes to install.  The RC file has
also been renamed to gmp3rc.

Now, speaking of themes, Gmp3's interface is now totally themified.  That
means that the main panel interface is defined solely by a themepack which
provides the graphics and layout for the interface.  Note, this is a brand
new feature, so it's possible there are many bugs.  Look out! :)  The
default themepack looks very similar to the standard Gmp3 interface (at
least at this point), but it gives a good idea of how to build themepacks.

An important thing to note is that currently there is no field in the
options dialog to define a themepack.  Therefore, if you want to load a
different theme (either located in the LIBDIR defined in the Makefile, or
in the users home Gmp3 configuration directory, add the following line to
your RC file:

themepack = <pack directory>


New Users Guide
---------------

Gmp3 itself is designed to be fairly easy to use.  The first thing that
should be noted when first starting the player is that the default theme is
rather minimalist.  In order to access any of Gmp3's features, right-click
on the panel.  This will pop up a menu from which you can make selections.

Another confusing thing about Gmp3 is how the playlist works.  This dialog
is broken up into 3 sections.  These are, in clockwise order (starting from
upper-left), the Albumn List, Song List, and Active Playlist.

The Albumn List contains all the song groupings available.  By default the
Assorted grouping is available.  Groups may be added or deleted by
right-clicking in the list box and selecting the appropriate option from the
menu.

The Song List displays all the songs available in the currently selected
Albumn.  To add songs to the Active Playlist, select the with the mouse,
right-click, and select "Add to Playlist".  From this menu you may also add,
delete, or modify existing song entried.

The Active Playlist.  This list contains all the songs which will be played. 
To add songs directly to the list, or remove songs, use the right-click to
pop up lists control menu.

One important, and decidedly irritating thing you may note is that if, for
example, you select an albumn with many songs, scroll to the bottom of the
song list, and then select an albumn with only a few songs, it may appear
that the song list doesn't display the songs in the Albumn.  However, this
is because the scroller does not reset.  If you scroll up, you will find the
songs available.  BTW, if someone knows how to fix this, let me know.  I'm
researching this one, but I'm not sure how to go about refreshing the
scrollbars.


Building Themes
---------------

Overview:

The themepack has only 1 requirement:  It must have a theme.rc file and must
have it's own directory inside the LIBDIR or the users .gmp3 directory.
However, this is not a limitation.  By using the %include directive, the
theme designer can include external files as part of the theme, and so
design the pack as they see fit.  They may also define a widgets.rc file,
which is a standard GTK rc file.  The description of the GTK rc file is
beyond the scope of this document, but information on it can be found at
http://www.gtk.org.  Now, there are various elements which make up a theme
pack.  The most important, however, is the window.


The Window:  

The themes themselves are fairly simple to design.  The theme itself is
broken up into two groups, namely big_window and small_window, which define
the large and small window sizes individually.  Now, like any other element in
the theme, the windows are defined with a "begin" followed by the window
identifier, and closed with an end, like so:

begin big_window
  ...
  ...
end

begin small_window
  ...
  ...
end

Now, the windows themselves have various attributes that can be defined. 
These are:

  size <width> <height>
  location <x> <y>
  background <image>
  
These are fairly straight forward.  The next three define the behavour of
the various mouse buttons:

  rightclick <action>
  middleclick <action>

We'll get into actions later, but for now, just remember they exist.  And
finally:

  titlebar <height>
  titlebarimage <image file>

These last two define the properties of the titlebar when Gmp3 is in
non-managed mode.  These define the titlebar height at the top of the window
and the image to be placed there.

Now, the main elements which exist inside a window are:  menu,
volume_slider, the labels, and buttons.  The following is a description of
each of these and how to define them.

NOTE:  All locations specified for the menu, volume_slider, etc, are
       relative to the window, not the titlebar (ie, the bottom-left corner 
       of the titlebar is considered (0,0) ).


Menus:

Each window can define a menu of it's own.  A menu is denoted by a "begin
menu", and each menu item is located on a seperate line.  The menu is then
closed by an "end".  The following is an example of a simple menu:

  begin menu
    item "Playlist Editor..." cmd_open_playlist_editor
    item "Quit" cmd_quit
  end

As you can see, each menu option is defined by the keyword "item", followed
by the menuitem text in quotes, and then the command action to be executed
by the menu.


Volume_slider:

Each window can define a volume slider.  This is a simple object, begun with
a "begin volume_slider", and closed with an "end".  The following is an
example of a volume_slider and shows it's properties:

  begin volume_slider
    orientation horizontal
    size 248 8
    location topleft 16 60
  end

Now, the "orientation" keyword is used to define the way the slider sits. 
This can be either "vertical" or "horizontal".  The next property is the
"size" property.  This defines the width and the height of the slider
widget.  The last is the location.  Now, this property defines the x and y
location of the slider with respect to the position specified.  In this
case, the slider is 16 pixels to the right and 60 pixels down from the
topleft corner.  Other possible locations are:  topright, bottomleft, and
bottomright.


Labels:

Now, each window has a specific set of labels it can define.  These are:

song_label - Label which shows the current song name.
time_label - The label for the timer.
repeat_label - This is the label used for the repeat indicator.
pause_label - Diddo for the pause indicator.
shuffle_label - And diddo again for the shuffle label.

Now, these all have the same properties and are defined like so:

  begin <label>
    ...
    ...
  end

where <label> is one of the identifiers listed above.  Now, each label can
contain the following properties:

  font <font string>
  color <r> <g> <b>    (values between 0 and 65535)
  location <pos> <x offset> <y offset>
  action <action-command>

Now, these are all self-explanatory, except possibly the "action" field. 
This field allows the user to define an action when the label is clicked on. 
This could be useful for, perhaps, toggling the shuffle status when the
label is clicked on.


Buttons:

These are an important part of the interface.  The window can have an
unlimited number of buttons (sanity permitting), and each is defined as 
follows:

begin button
  ...
  ...
end

Now, the properties that a button can have are:

  default <image file>
  focused <image file>
  pressed <image file>

All these define the various states of the button.  For example, the default
image is the normal appearance of the button, "focused" defines the image
when the button is pointed at, and "pressed" is the image when the button is
pressed.  Other properties are:

  location <pos> <x offset> <y offset>
  action <action-cmd>
  tooltip <tip string>

These are all self-explanatory.


Actions:

Now, actions are an important part of the theme.  The following action
commands are valid:

cmd_back - Previous song
cmd_forward - Next song
cmd_play - Play song
cmd_stop - Stop playback
cmd_pause - Pause playback
cmd_toggle_shuffle - Toggles the shuffle status
cmd_toggle_repeat - Toggles repeat status
cmd_toggle_size - Toggles the window size between the big_window and
                  small_window.
cmd_open_playlist_editor - Opens the playlist editor.
cmd_open_options - Opens the options dialog.
cmd_open_about_box - Displays the program about box.
cmd_popup_menu - This command pops up the window's menu.  Note, this command
                 doesn't work the greatest with buttons.  Note, it works,
                 but not nicely. :)
cmd_quit - Quits gmp3.

All these can be used where an action is required in a widget.


Final Notes:

The themes in Gmp3 are a new feature.  As such, they may be buggy.  What's
more, this is the first time I've designed a theme-based application, so the
format itself (in particular, the method of defining labels), is really a
kludgey way to accomplish things.  Unfortunately the current theme setup
isn't as flexible as I want it (the titlebar, for example, is limited to the
upper portion of the window).  However I hope to make things a little more
elegant in later releases (to the point of a complete rewrite, possibly). 
Enjoy what I have done, though! :)
