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.x will work)
- GDK_Imlib 1.3+
- The following libraries (for use with gdk_imlib):
    libjpeg
    libpng
    libtiff
    libgif
    zlib
- 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 device is NOT required.  It's simply needed for the built-in mixer to
function.


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

What's new this time?  Well, some pretty fundamental things have change in
Gmp3.

1) You don't need a patched version of mpg123 any more!  Yes, that's right! :)
   I finally realized the joy of process groups... man I love those
   things...

2) Gmp3 will correctly run scripts, so this means you can wrap any sound
   player you like or write interesting wrapper scripts for mpg123... see
   the scripts directory for some examples of possibilities.

3) The theme code has been cleaned up.  Certain things about the themes
   have changed, so make sure you install over top the old default theme.
   If you've created any new themes, you'll have to update them.  Here are
   the major changes:

   1. CMD_OPEN_PLAYLIST_EDITOR changed to CMD_OPEN_ALBUMN_EDITOR
   
   2. New command, CMD_OPEN_PLAYLIST_EDITOR, which opens the active playlist
      window.

   3. drag_bar identifier removed from window properties.

   3. New command CMD_DRAG_CAPTURE, which is used to capture the mouse for
      window dragging.  Use this as the left-click action for a window to
      make it draggable.

   4. CMD_FOWARD corrected to read CMD_FORWARD... whoops!  The old command
      is still retained for backwards compatibility.

4) The rcfile saving stuff is changed... look for bugs here, as I hacked
   (and I mean HACKED :) together this code way too late at night for my
   own good. :)  Of course, this just means the code fits right in with the
   rest of the program...

5) Support (sort of) for HTTP streaming.  Basically, you can now type in
   URL's in the file selection box and mpg123 will play them.  With this
   comes a couple new options for http proxies and authentication strings.
   Note, the HTTP stuff has been tested sparingly. :)

And, of course, lotsa new bugs to keep the old-timers company. ;)

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.

The playlist system is (hopefully) fairly simple and intuitive.  There are
two main objects, the Albumns and the Active Playlist.  The Albumns are
essentially a database of songs that can be catagorized to your needs.  The
Active Playlist contains a list of all the songs queued up to be played.  To
add songs to the Active Playlist, select the various songs from the albumn,
right-click, and select "Add to Playlist".  You may also add songs directly
to the playlist by clicking in the playlist widget, right-clicking, and
selecting "Add Song(s)...".  This is the same method you would use to add
songs to an albumn.  To remove songs from an albumn or the playlist,
select the songs, right-click in the list, and select "Remove Song(s)..."

Essentially, all operations which can be done on albumns or songs are
available by right-clicking in the appropriate list.


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>
  mask <image>
  tooltip <text>
  
These are fairly straight forward.  The "tooltip" field defines the message
displayed when the user points at the main window.  The "mask" field defines
a transparency mask for the window.  Note, currently this makes the window
non-managed despite the setting to the "managed" flag in the gmp3rc file.

The next three define the behavour of the various mouse buttons:

  leftclick <action>
  rightclick <action>
  middleclick <action>

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_drag_grab - Basically, this command causes the mouse to be grabbed for
                dragging.  Don't use this with menus... it won't do
                anything. :)
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_albumn_editor - Opens the albumn editor.
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 m9enu.  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.


Acknowledgements
----------------

Currently, this list is fairly short, but, hopefully it will get larger as
time passes. :)

mpg123 Authors - Thanks for the best MP3 decoder around... you kick arse! :)

GTK developers - Another awesome group.  Thanks a lot for a great toolkit!

Marek Blaszkowski - I got my mp3 tag loading code from this guy. Thanks!

Florian Hinzmann - This fellow just keeps reminding me that Gmp3 exists and
  needs a lot of improvement. ;) He's got a lot of good ideas and, without
  realizing it, has pushed me along a bit.  Thanks! :)

The Linpeople folks - You guys were EXCELLENT help for learning Linux
  programming.  Gmp3 wouldn't be here without you guys!  (you can decide
  if this is a good thing or not).  Of course, as is obvious, you can't
  teach how to create *quality* code, BUT... ;)

Everyone who's sent in emails with bug reports, fixes, or just
comments/criticisms, thanks!  

I hope to have this player get better and better as time passes.  This has
been a really fun pet project for me, and a great way to learn Linux/GTK
programming... let's see where it goes.