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

First of all, this section is for users upgrading from version < 0.07. 
These Past users need to convert their playlists.  To do this, use
the convlist program provided.  It's syntax is:

convlist < infile > outfile

Now, really the only fundamental change to Gmp3 in this version was a
complete rewrite of the playlist editor.  This means a few things.  1) You
have to convert your playlists over to the new format.  This is because the
new albumn editor supports subgroupings for the songs (ie a tree-like
structure).  2) The editor is now broken down into two windows.  One is the
albumn editor, and the other is the active playlist editor.  I've seperated
them to reduce screen space usage, as well as to emphasize their rather
seperate functionality.  With this seperation, you can also save the active
playlist seperately from the albumn database, so you can always reload those
great mixes you've put together. :)

I hope you enjoy this new version.  The new playlist editor is much faster
and more efficient than the previous one (I learned from my mistakes :), and
has a much leaner design (although you couldn't tell by the amount of code
for it...)  Enjoy! :)

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:

  rightclick <action>
  middleclick <action>

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

  dragbar <x> <y> <width> <height>

This last one defines a region of the window which can be clicked and
dragged to move the window.  This can be used for creating a handle,
titlebar, or whatever.

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


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! :)


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! :)

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. :)

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. :)
