Remove events_pending

[gmpc.git] / doc / Manual.txt

GMPC v0.14.0 Manual
===================
Qball Cow <qball@qballcow.nl>
v0.2, December 2006



{index}

Quick Starters Guide
---------------------

If you start gmpc for the first time you see the following default window:

.The Main Window, Disconnected
image::images/gmpc-mainwindow.png["The Main Window, disconnected"]

To connect to mpd, you first need to enter the location of mpd. You can do this in the preferences window.
(Music->Preferences)

.The Preferences dialog, Connection
image::images/gmpc-preferences-connection.png["The Preferences dialog, Connection"]

Enter the correct information and click *Connect* and close the preferences window.

.The Main Window, connected
image::images/gmpc-mainwindow-connected.png["The Main Window, connected"]

If you haven't used anyother client with mpd yet, you won't see any music in the playlist. 
You need to add music from mpd's database to the playlist. In gmpc you can do this in different ways, for example using the File brohttp://qballcow.nl/Guide/Manual.htmlwser.

.The File Browser
image::images/gmpc-filebrowser.png["The File Browser"]

The file browser acts like any other file browser. You can browse through the music in the way it's stored on the file-system.

[NOTE]
If you don't see any folders of music here, it's possible mpd's database haven't been updated yet. You can do this by right-clicking on the "Browse Filesystem" and select update. If this doesn't work (it might take some time), please look at mpd's link:http://mpd.wikia.com[Wiki]

To add a folder, or music-file right click and select add (or press insert-key to add the selected items).
You will see a message in the status bar.

.The File Browser, adding a folder
image::images/gmpc-filebrowser-add.png["The File Browser, adding a folder"]

You can now press "Play" to enjoy your music.

.Gmpc Playing
image::images/gmpc-mainwindow-playing.png["Gmpc Playing"]

TIP: To get cover art in gmpc, you need to install provider plugins

[[X20]]
Main Window
-----------
Interface
~~~~~~~~~~~

The main window consist of everything beside the browser. It features the player controls, and the posibility to switch from one browser to the other.

.Main window 
image::images/gmpc-mainwindow-playing.png["Gmpc Playing"]

The main window can be devided into 4 parts:

1. Menu Bar
2. Player
3. Browser
4. Status bar

1. Menu Bar
^^^^^^^^^^^

image::images/mainwindow-menubar.png["Menu Bar"]

The menubar provides quick access to most functionality in gmpc.
The structure can vary depending on the state gmpc is in, but it basically looks as follow:

- Music
  * Connect
+
        Connect to the currently selected profile.
+
  * Disconnect
+
        If connected, disconnect
+
  * Send Password
+
        If you are connected to a mpd that has limited permissions, you can use this command to authenticate to get extra permissions. 
+
  * Profiles
+
        Shows in a sub-menu a list of available profiles. 
+
  * Preferences
+
        Opens the preferences window
+
  * Quit
- Control
  * Play/Pause
+
        Start playing, or if pause a playing song.
+
  * Stop
+
        Stop playback
+
  * Next
+
        Skip to the next song
+
  * Previous
+
        Go back to the previous song, 
+
  * Repeat
+
        Enable/Disable repeat mode
+
  * Random
+
        Enable/Disable random order playback
+
- View
  * <<X22, Expand Interface>>
  * <<X22, Collapse Interface>>
  * Show current song information #make link
+
        Calls the Song information window for the currently playing song
+
  * Show artist image
+
        Gmpc can show, if available, a image of the artist in the lower left corner.
        This lets you turn that image on/off
+
- Option
+
        The option menu shows the available options that the current selected browser provides, it is equal to the context menu of the left treeview.
+
- Go
+
        The go menu provides a easy way to access the different browsers.
+
- Help
  * About

2. Player 
^^^^^^^^^

image::images/mainwindow-player.png["Player"]

The player gives you quick access to the default player controls. (Need a nice story here)

TIP: You can quickly jump to a position in the song by middle clicking on that position in the progress slider.

NOTE: To get cover art in the player you need to install the correct plugins that provides them to gmpc.

3. Browser
^^^^^^^^^^

image::images/mainwindow-browser.png["Browser"]

In the left tree-view you can browse through the browser and the different browsers. Depending on what browser selected the right pane will show the content. This can be a list view, f.e. the current playlist but it can also embed firefox to show you a wikipedia page (the wikipedia plugin does this). 

4. Status Bar
^^^^^^^^^^^^^

image::images/mainwindow-statusbar.png["Status Bar"]

The status bar consists of 2 parts. On the left you see short term information messages, like 'Added 5 songs'. 
On the right you see information about the current browser, for example in the Current Playlist you see the total time of the playing list.

NOTE: Plugins/browsers are allowed to add widgets to the status bar, so does the file-browser show a small icon in the status bar when mpd is updating it's database.

Keybindings
~~~~~~~~~~~

.Keybindings Player:
[frame="all",grid="all"]
`--------------`-----------------
Key combination Command
------------------------------
Ctrl - Right    Skip to next song
Ctrl - Left     Skip to previous song
Ctrl - Up       Play/Pause
Ctrl - Down     Stop
Keypad 6        Skip to next song
Keypad 4        Skip to previous song
Keypad 8        Play/Pause
Keypad 5        Stop
Ctrl - s        Random on/off
Ctrl - r        Repeat on/off
----------------------------


.Keybindings Interface:
[frame="all",grid="all"]
`--------------`-----------------
Key combination Command
------------------------------
Ctrl- '+'       <<X22,Expand interface>>
Ctrl- -         <<X22,Collapse interface>>
Keypad +        <<X22,Expand interface>>
Keypad -        <<X22,Collapse interface>>
F1              Go to <<X30, 'the current playlist'>>
F2              Go To <<X35, 'the playlist search browser'>>
Ctrl- j         Goes to <<X35, 'the playlist search browser'>> and allows you to directly type in a search.
F3              Go to <<X40, 'the File browser'>>
F4              Go to <<X50, 'the Artist browser'>>
F5              Go to <<X60, 'the database search browser'>>
F6              Go to the Information view
F7              Go to the meta browser

------------------------------

[[X22]]
Interface Expanding/Collapsing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The main window has 3 possible sizes:

Full mode 
^^^^^^^^^
Everything is visible. 

.Full mode 
image::images/gmpc-full-size.png["Full mode"]

Small mode
^^^^^^^^^^
Hides the Left treeview, and replaces it by a Selection box.

.Small mode 
image::images/gmpc-small-size.png["Small mode"]

Tiny mode 
^^^^^^^^^
Only shows the player elements.

.Tiny mode 
image::images/gmpc-tiny-size.png["Tiny mode"]

[[X30]]
Current Playlist
----------------

image::images/gmpc-mainwindow-playing.png["Gmpc showing the 'current playlist' browser"]

Moving songs around
~~~~~~~~~~~~~~~~~~~
You can drag and drop songs in the playlist by selecting them and 'dragging' them to the new location. At the moment this is only posssible for one song at the time, due to limitations in gtk.


Column Selector
~~~~~~~~~~~~~~~
From the right mouse menu on the current playlist you can open the column selector.

image::images/current-playlist-column.png["Column Selector"]

The column selector lets you enable,disable and move columns around. 

TIP: You can also move columns directly in the browser by dragging them around.

Context Menu
~~~~~~~~~~~~

When right clicking on gmpc, you get a small context menu with the following options:

[frame="all",grid="all"]
`---------------`------------------------
 Action          Result
--------------------------------------
Remove          Removes the selected songs
Crop            Removes all, but the selected songs
Clear           Clears the playlist
Shuffle         Shuffles the order of the playlist
Information     Shows the song information of the selected songs
Column          Opens the column selector
-------------------------------------

Option Menu
~~~~~~~~~~~

You can get to the option menu by right clicking on the 'browser selector' or selecting 'option' from the menu bar.

[frame="all",grid="all"]
`---------------`------------------------
 Action          Result
--------------------------------------
Save            Saves the current playlist
Clear           Clears the playlist
Add Url         Opens the add url window, that allows you to add a stream to the playlist
-------------------------------------

NOTE: Plugins are allowed to add entries to the option menu.

Keybindings
~~~~~~~~~~~
The keybindings will only work when the input focus is on the current playlist browser.

.Keybindings Current Playlist:
[frame="all",grid="all"]
`---------------`----------------------------------------
Key combination Command
---------------------------------------------------------
Del             Delete the currently selected songs 
Enter           Play the first selected song
Alt - i         Show song info about the selected songs
Space           Show and select the current song
Any character   Start a search as  you type.
---------------------------------------------------------

TIP: If you don't want to view metadata in columns, you can return to the 'old' behauviour by selecting 'Markup' in the column-selector. Then you can change this markup in the preferences window.

[[X35]]
Playlist Search Browser 
-----------------------

Keybindings:


[[X40]]
File Browser
------------

Keybindings:


[[X50]]
Artist Browser
--------------
Keybindings:


[[X60]]
Database Search Browser
-----------------------
Keybindings:


[[X100]]
Advanced features
-----------------

Gmpc can be further configured by directy edited the config file. If you edit the configuration file directly make sure gmpc isn't running.
There configuration file is stored in '~/.gmpc/' and is called 'gmpc.cfg'.

The following extra changes can be made:

1. *playlist::background-load-playlist*: Gmpc's playlist works using a lazy loading model.  It only loads the song info of the visible songs, this increases startup speed, and saves allot of (startup) bandwidth. But it does make searching the playlist slow the first time.  With this option gmpc starts filling in the missing data of the playlist in the background. (This can slow gmpc down when connected to mpd using a very slow connection) 
2. *playlist::player_markup*: This allows you to change the way gmpc displays the song information in the player part of the window. Editing this markup you should keep in mind that the processed result is a valid pango markup. (see pango documentation).
3. *Default::allow-multiple*: Gmpc normally only allows one instant per user to be running, with this option you can turn that extra check off.  (This option only works when gmpc is compiled with session support).
4. *connection::mpd-update-speed*: Change the speed gmpc poll's mpd for status/state changes. The value denotes the time between checks in ms. 
5. *connection::profile-file*: Gmpc stores the created profiles in a separate config file, with this option you can change the location of this file.
6. *tray-icon::y/x-offset*: Change the x/y offset the tooltip makes relative to the corner it's placed at.
7. *tray-icon::middle-mouse-action*: Change the behavior middle mouse clicking on the tray icon. Valid values are: pause,play,next,prev,stop 
8. *cover-art::browser-size*: Change the size of cover images in the browsers. At the moment this has only effect on the artist browser.

[[X110]]
FAQ
---

A collection of frequently asked questions.