Layout documentation

Introduction

Gmusicbrowser's interface is defined by layouts. Each layout define a window that contain several containers, each containing widgets.
Layouts are used in many places in gmusicbrowser : the main window, the "traytip" popup, the fullscreen mode, the search and browser windows, pages that can be inserted as a tab, desktop widgets (plugin), the titlebar overlays (plugin), as well as some internal windows (such as the queue, equalizer).

Note that this documentation is likely incomplete, and could be improved. Don't hesitate to suggest improvements, ask for clarification, or point out missing informations.

Advice for testing layouts

Experimenting with layouts is highly encouraged. When doing so, it is recommended to launch gmusicbrowser from the command-line as some layout errors can be printed on the terminal. A good way to do that is launch gmusicbrowser with the -layout (or -l) followed by the layout identifier, this will directly open the desired layout. You can then easily quit without saving by pressing ctrl-c in the terminal, an advantage of this exit method is that it always works (no matter what your layout contains) and that no setting for the layout will be saved, so that you can see it each time as a new user would. Note that the auto-save plugin might still save the options, the -demo option will prevent any writing of the gmbrc. You can also use a copy of your gmbrc file and use the -cfg option to tell gmb to use the copy.

Layout files

Layouts are defined using text files, each file can contain one or more layout.
Layout files use the .layout extension, they are found in 2 places:

Layout syntax

A layout definition begins with a line containing a layout identifier enclosed in square brackets ([]) such as: [some_layout_id].

(Layouts files may also contain group and column definition for the SongTree widget (see the SongTree documentation for details). These group and column definitions begin with lines between {}. The definitions include all the following lines up to the next [] or {} line, or to the end of the file.)

layout definition syntax :

[layout_id]
key1 = value
key2 = value
...

layout_id is the string used to identify the layout. It can contain spaces or other special characters but it is recommended that only alphanumeric characters (A-Z, a-z, 0-9 and _) be used, otherwise it may harder or impossible to use the layout with some advanced features. If you want to give the layout a nice name use the Name property explained below.

Long lines can be be split into multiple lines by ending them with a backslash (the backslash is optional as long as the next line doesn't begin with something like word=).
Keys define either containers or properties, they only use simple alphanumeric characters : A-Z a-z _ 0-9 .
Keys are unique for a layout, duplicate key definitions replace the previous one.

If the name of the key begins with one of : HB, VB, HP, VP, MB, EB, TB, FR, NB (and some others, see below) the key is the name of a container that will contain widgets (also called layout elements or controls) or other containers.
For containers the value is a list of children (widgets and/or other containers), separated by a space and preceded by optional packing options. The widget names can be followed by a number (to have multiple widgets of the same name) and its options between parentheses.

There must be one, and only one, container which has no parent, this container will be put in the layout window.

Simple examples

Very simple example, with 3 buttons (settings, play/pause, and open browser window) and the current song title :

[very_simple]
Type = G
HBox = Pref Play OpenBrowser _Title

Type=G (G for generic) is used to make it appear in the player layouts list in the settings dialog. The _ before Title is used to make the Title use all the available space in the horizontal box (HBox) it is packed in. The 4 widgets are put into a HB (= horizontal box) container, so they will be placed in a line.

[simple]
Type=G
VBmain = MBmenu HBbuttons Title Text(markup="<i>by</i> $artist <i>in</i> $album")
MBmenu = MainMenuItem
HBbuttons= Prev Play Next

This layout has 3 containers, VBMain being the parent widget for MBmenu and HBbuttons. The Title widget displays the current song's title and Text has an option that defines what it should display, complete with pango markup and $-words. This layout will show, vertically : a menu, buttons, title, and the text widget showing artist and album.

Look in the layouts files (installed in /usr/share/gmusicbrowser/layouts/) for more examples.

Normal containers

Containers are used to organize the widgets inside the window. They accept options that must be specified in parenthesis before the child widgets list. For example :

HBname = (option1=value1,option2=value2) widget1 widget2

All containers accept the option border to specify the amount of padding around the container.

HB/VB : Horizontal/Vertical Boxes (based on GtkBox)

These containers group widgets horizontally or vertically. Optional packing options are :

HP/VP : Horizontal/Vertical Panes (based on GtkPaned)

Same as HB/VB but they contain only 2 widgets
They only have one packing option, the underscore _. It sets the expand propriety that tells the container that this widget should give or receive space when the container is resized.
If both children have the expand propriety, they will both give or receive space when the container is resized.

TB : Notebook (based on GtkNotebook) (deprecated)

Each widget is in a tab, no packing options but the syntax is a bit different, each widget is preceded by the tab title.
The title can have spaces by using quotes, for example :

TBname = title1 widget1(options) "title with spaces" widget2(options) title3 container3

NB : Notebook (based on GtkNotebook) (new version)

No packing options, syntax is simply the list of children.

A title and an optional icon is given by children options tabtitle and tabicon. For example :

NBname = widget1(tabtitle="a title",other_option=value) widget2(tabtitle="other tab",tabicon=gmb-list) widget3(tabtitle=third)

Tab position and rotation can be set by using tabpos option, which can be one of left, right, top, or bottom, optionally followed by an angle : 0, 90, 180 or 270
Example :
NBname = (tabpos=left90) children1 children2

The hidetabs=1 container option can be used to hide the tabs, this is meant to be used with commands that use SetFocusOn to change the visible page/child

As this container is in fact a TabbedLists/Context with different default options, it also accept the TabbedLists/Context widget options.

EB : Expander (based on GtkExpander)

Contains only one child, that child can be shown/hidden by clicking on the expander Option : label sets the text that will be displayed next to the expander.
Examples :

EBname = (label="optional label") widget1`  
EBsimple = widget2`

FB : Fixed (based on GtkFixed)

Each widget is positioned at precise coordinates
Syntax : FBname = x1,y1 widget1 x2,y2,w2,h2 widget2 ...
The widget is positioned at the x,y coordinate.
An optional width and height can follow the coordinates, to specify how much space the widget should use. An height or width of 0 means leave it as default.
x,y,w,h can be relative to the width/height of the container by preceding the number with a dot (.)
x,y can be relative to the right/bottom border by prefixing it with minus (-).

MB : Menu Bar

They can only contain MenuItem widgets or SM containers, no packing options

SM : Submenu

They can only contain MenuItem widgets or SM containers, no packing options, label is set with the label container option

BM : Button menu

They can only contain MenuItem widgets or SM containers, no packing options.
Container options :

FR : Frame (based on GtkFrame)

Draw a border around its child, with an optional label. (Can only contain one child)
Container options :

SB : Scrolled window (based on GtkScrolledWindow)

Adds scrollbars to its child. (Can only contain one child)

AB : Alignment (based on GtkAlignment)

Controls the alignment and size of its child. (Can only contain one child)
Container options :

WB : Event window

This container is used to have control over the background or mouse events on its child. (Can only contain one child) Some containers and widgets (like HB/VB) do not have their own gdkwindow and thus can't control their background or mouse events. Putting them inside a WB allows working around that. For example for having a window pop-up when the mouse is above a HB container, using the hover_layout option on the HB won't work, but putting the HB inside a WB and using the hover_layout option on the WB will work. It's also a way to paint the background of a HB using a custom gtk theme.

Special containers

There is also 2 special containers, widgets in these containers must belong to a normal container, and as the widget is defined elsewhere, widgets options can not be set here. These containers can be viewed as layout properties that take a list of widgets as value.

HSize/VSize : Size groups (see GtkSizeGroup)

Force all widgets to have the same Horizontal/Vertical size, if the list of widgets begin with a number, the first widget Horizontal/Vertical size will be set to this number (in pixels)
Example :

HSize0 = 20 widget1 widget2
HSize1 = widget3 widget4

VolumeScroll :

A unique virtual container (must be the exact name). For all widgets or containers inside, the scroll wheel will modify the volume (unless the scroll event is intercepted, like in a scrollable list).
Example :

VBmain= Title HBbuttons TimeBar
HBbuttons= Pref Play
VolumeScroll= Title HBbuttons

Layout properties

Title

Set a title for the window. If not set, the window title defaults to Song Title by Artist (%S by %a) (see %-letters and $-words)

Title = gmusicbrowser playing %S by %a from %l

Type

A String of letters (most of the time only one letter) defining the type(s) of a layout, possible types :

Name

Set the name of the layout displayed in the settings dialog. The default Name is the layout id.
Contrary to the layout id, the Name can be changed without losing the layout's saved settings (window size, ...).
The name can be marked as translatable by using the syntax Name= _"name of the layout"

Title and Icon

Used to define a tab title and a tab icon if the layout is used as a page in a NB/TabbedLists/Context

Default (mostly deprecated)

Default options used when the layout has no saved state, contains a space-separated list of keys and values, by pair, widget_or_container_name widget_or_container_variable_options.

There is a special key : Window, for the window properties, see the Window layout property below.

Example :

Default = Window size=1120x820,sticky=0 HPbig 780 FPane0 page=artist

This is mostly deprecated as now default options can be specified among the normal widget options, but it is still used a bit, in particular for HP/VP containers.

KeyBindings

Pairs of keys and action, example :

KeyBindings = Insert OpenSearch c-q EnqueueSelected c-Insert OpenCustom(a_layout_id)

Key names are as shown in the key binding tab in the settings dialog.
Commands can be found by running gmusicbrowser with command-line option -listcmd.

DefaultFocus

Set which widget gets the initial focus in the window. It might not work with some complex widgets though it is easy to fix, just ask me if you'd like to enable it for a widget that currently doesn't support it.
Example :

HBmain= Pref Play _Title
DefaultFocus= Play

DefaultFont and DefaultFontColor

Set a default font and font color for widgets that use a font or a color option.

SkinPath and SkinFile

Used to set a picture file to be used as a skin, that can be used to set a window background, see the skin documentation.

Window

Set some window options :

Derived layouts

A layout can be derived from a previously defined layout by adding based on, followed by the layout id of the layout it is based on:

[layout_id] based on this_other_layout_id

In this case the layout starts with all the key definitions of the other layout, each key can be re-defined or deleted (if nothing follows the =).
This method of deriving layouts is only recommended for very small variants where only one or two line changes, as it might easily break if the original layout changes.

Widgets

Widgets options

Widget options are specified in the layout definition, in parentheses, after the name of the widget. Options are a list of keywords and values, separated by commas (with optional spaces). For example :

VBmain= widget1(key1=value1,key2=value2, key3=value3) widget2(anotherkey=somevalue)

There are 2 kind of widget options. The first one (let's call them layout-set options) are the options that can only be set in the layout definition, most of the options described in this document are of this kind. The second kind (let's call them user-set options) are the options that the user can change in the GUI and are saved when the window is closed. The layout definition can change the default value of the user-set options, but if the user has already used the layout once, the user-set options will use their last recorded value and ignore the value set in the layout definition. As mentioned earlier, you can use the -demo command-line option to prevent the user-set options from having a recorded value and be able to test the value set in the layout definition.

Most of these user-set options are not documented here. To discover them you just need to use the widget in a layout and then look at the file containing the saved options (~/.config/gmusicbrowser/gmbrc) for the line containing the layout id, then for the line containing the widget name, the following lines contain the saved widget options. Some of these options may contain sub-options (for example a FilterPane has a set of sub-options for each of its page), a default for these sub-options can be set in the layout by using a slash (/) to separate option and sub-option. Example : FilterPane(page_album/mode=mosaic)

In the future, some of the layout-set options may become user-set options, as more options are exposed to the GUI.

Generic widget options

A number of options work on a lot of widgets and containers

size options

click options

A lot of widgets, in particular text labels, indicators and buttons can use the option click1 (or click2 ...) to (re)define the action executed when the widget is clicked with mouse button 1 (or 2 ...).
Example : Play(click2=OpenSongProp)
Button widgets also accept the option activate to (re)define the action executed when the button is activated with a mouse click or keyboard

tip option

A lot of widgets, in particular labels, indicators and buttons can use the option tip to define a tool-tip for the widget. The tip may contain %-letters and $-words to display informations on the current song.
Example : Title(tip="last played : $lastplay")

cursor option

Another common option, it is used to change the mouse cursor when it hovers over the widget.
Example : Play(cursor=hand2)
See this page for a list of cursor names.

hover_layout option

Many widgets and containers can use the hover_layout=ALayoutName option. It causes a window using the ALayoutName layout to pop-up when the mouse hover on the widget (for more than 1000ms, or the value set by the hover_delay option, use 1000ms if set to 0). The popped-up window disappear when the mouse exit the window.
Only the widget or container that have their own gdkwindow can use this option. For the other widgets/containers, they can be placed inside a WB and use the hover_layout option on this EW.
The hover_layout_pos option can used to control the position of the popped window, see this commit
Simple example of the hover_layout option to popup a big cover when the mouse hover on a Cover widget, by defining the Cover widget with this option : Cover(hover_layout=CoverPopup), where CoverPopup is the the layout :

[CoverPopup]
VBmain= Cover(minsize=800,maxsize=800,click1=CloseWindow)

To make the layout popup when the Cover widget is clicked rather than hovered, use this option : Cover(click1=PopupCustom(CoverPopup))

group option

The group option is used to link a widget to a songlist (or equivalent widget) or to a song or set of songs. There are 2 type of links associated with the group option (they will be separable in the future), links to 1 song (like the current song or the last clicked song in a songlist), and the links to a set of songs (like the playlist or the content of a songlist), most widgets only use one type of links, some use both.

If the group option is not specified, most filter-oriented widgets (like songlist and FilterPane) will use a default group, local to the window. The song-oriented widget will often default to the group Play (like the Title/Artist/... widgets) to follow the current song.
Group names that begin with an upper-case letter are global, the others are local to the window.
There are a few special predefined groups :

Examples :

Options common to the text widgets

The text widgets (sometimes called label widgets) include : Title, Title_by, Album, Artist, Comment, Year, Length, PlayingTime, Pos, and Text

Text widgets

Buttons widgets

The OpenContext, OpenBrowser and OpenQueue buttons accept the option 'toggle', if true (=1) the button will close the opened window if it is already opened

All buttons can be changed to an indicator(no button border, smaller) with the option button=0

Relief can be changed for buttons by using the option relief=none (default), half or normal.

Size of buttons and indicators can be set by setting the option size to menu, small-toolbar, large-toolbar, button, dialog, dnd (the actual size depends on gtk settings)

Indicators widgets

All indicators can be changed to buttons with the option button=1. Size can be changed same as buttons, see above.

indicators (Filter Queue Sort ...) and some buttons (Play Next Prev Stop Quit ...) have a few common options:

Time widgets

Volume widgets

Other widgets related to the playing song

By default, all these widgets show information on the currently playing song, some allow the edition of a property of the current song. By using the group option (see above), these widgets should be able to follow for example the selected song in a songlist rather than the current song. Example : VBexample= _SongList(group=example) Cover(group=example)

Miscellaneous widgets

Songlist widgets

When there is more than one SongList/TabbedLists/... in a layout, they must each but one be assigned a group number though the group option. The one without a group number will be the default with which other widgets interact with.
All the other widgets which interact with a SongList/TabbedLists/... accept the option 'group' to specify which one they interact with, it is only needed when the layout contain more than one SongList/TabbedLists/...

Widgets related to songlists

(filter# is a number between 0-9, 0 is meant for FilterLock, when a filter is set all filters with a higher number are reset)
All these widgets accept the option group to specify which SongList/TabbedLists/... they interact with, it is only needed when the layout contain more than one SongList/TabbedLists/...

MenuItem widgets (can only be put in a MB/SM)

Widget aliases

Some widgets have been renamed, the old names are deprecated but can be found in old layouts.
old name => new name :

Playlist    => OpenBrowser
BContext    => OpenContext
Date        => Year
Label       => Text
Vol         => VolumeIcon
LabelVol    => Volume
FLock       => FilterLock
TogButton   => ToggleButton
ProgressV   => VProgress
FBox        => FilterBox
Scale       => TimeSlider
VolSlider   => VolumeSlider
VolBar      => VolumeBar
FPane       => FilterPane
LabelTime   => PlayingTime

Embedded layouts (experimental)

Layouts can be embedded inside an other layout by simply adding \@id_of_embedded_layout to a container (not all characters are supported in embedded layouts identifier)
example :

[example_layout]
HBmain = Play Stop Pref
VBmain = HBmain Title _@embedded_example

[embedded_example]
VBmain = Title _SongTree

%-letters and $-words

Some options accept %-letters and $-words variables that are replaced by a field/property of the currently playing song. For example in %t by %a, %t is replaced by the song title and %a by the artist name. It is equivalent to $title by $artist
Note that %c and %f are not meant to be used for displaying.

$-words : the word can be any of the activated field name, see the fields tab of the settings dialog.

%-letters :

t   title
a   artist
l   album
d   disc
n   track
y   year
C   comment
p   play count
P   last play
k   skip count
K   last skip
g   genres
L   labels
m   length
V   version or nothing if song doesn't have a version/subtitle tag
S   title or filename if no title
f   filename (with path) (raw filename, may not display correctly)
u   filename (with path) (in utf8, used for display, might not be convertible back to the real filename)
c   cover file
Y   album year(s)
A   album artist or artist