Differences

This shows you the differences between two versions of the page.

--- customization:layouts:latest_version [2010/09/20 11:33] – satoshi
+++ customization:layouts:latest_version [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-======= Latest Version Layout Documentation ======
-gmusicbrowser - layout documentation
-This is the documentation for Gmusicbrowser layout system. It tries to follow the latest git version closely, however, since the software is in active development, this is not guaranteed to work with the latest git version. Also, due to to ever-evolving syntax and features, not all of this will work with the latest unstable version (1.1.5 as of this writing). If you are interested in the legacy documentation for version 1.0.2, please see [[customization:layouts:oldgmb|this page]]
-(the syntax is evolving, but I try to support backward compatibility)\\
-//Updated on 08-07-2008// : added the forgotten Button widget, and the stock option that can be used by buttons widget\\
-//Updated on 06-07-2008// : added the forgotten markup option for labels widget, and the %-letters section\\
-//Updated on 06-05-2008// for gmusicbrowser v0.964
-Gmusicbrowser's interface is defined by layouts.
-Layouts are found in 2 places:
-  * the default layouts installed with gmusicbrowser are in /usr/share/gmusicbrowser/layouts when installed
-  * custom layouts can be added by placing them in ~/.config/gmusicbrowser/layouts (or ~/.gmusicbrowser/layouts if you have started using gmusicbrowser before v0.963), which can be either a file or a folder containing multiple .layout files (read in alphabetical order)
-layout file format :
-	[layout id]
-	key1 = value
-	key2 = value
-	...
-As of version 0.962, layouts file can contain group and column definition for the SongTree widget. See the [[customization:songtree|SongTree documentation]] for details.
-long lines can be be splitted in multiple lines by ending them with a backslash
-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 Playlist _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.
-Look in the layout file for more examples.
-Keys define either containers or properties.\\
-Keys are unique for a layout, duplicate key definitions replace the previous one.\\
-There are currently 6 properties keys (Type, Name, Default, Title, KeyBindings, ExtraWidgets) which I'll describe later.\\
-If the name of the key begins with one of: HB, VB, HP, VP, MB, EB, TB 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 widgets and containers, separated by a space, 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.
-===== Normal containers =====
-Containers options can be specified in parenthesis before the child widgets list, example : ''HBname = (option1=value1,option2=value2) widget1 widget2'', all containers accept the option border, that specify the amount of padding around the container.
-**HB/VB** : Horizontal/Vertical Boxes (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkBox.html|GtkBox]])
-optional packing options are : (they must be in this order)
-  * number  : padding (in pixels)
-  * _  : expand (the widget will use all remaining space in the container)
-  * -  : right aligned
-  *
-example : ''HBname = 2_-widget1(opt1=val,opt2=val) -widget2 2container3''
-Cover and ArtistPic widgets are treated specially, they ignore the expand mode, and expand until they reach a square size. example : in a HBox which has a height of 30, a Cover widget will use available space to expand if it has a width less than 30.
-**HP/VP** : Horizontal/Vertical Panes (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkPaned.html|GtkPaned]])
-Same as HB/VB but they contain only 2 widgets
-And they only have one packing option : ''_'' (expand)
-**TB** : Notebook (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkNotebook.html|GtkNotebook]])
-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
-example : ''TBname = title1 widget1(options) "title with spaces" widget2(options) title3 container3''
-**EB** : Expander (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkExpander.html|GtkExpander]])
-contains only one widget/container which can be showed/hidden
-option : label : text for the optional widget syntax : ''EBname = (label="optional label") widget1''
-or : ''EBname = widget1''
-**FB** : Fixed (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkFixed.html|GtkFixed]])
-Each widget is positionned 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 '.'
-x,y can be relative to the right/bottom border by prefixing it with '-'.
-**MB** : Menus
-They can contain only MenuItem widgets or SM containers, no packing options
-**SM** : Submenu
-They can contain only MenuItem widgets or SM containers, no packing options, label is set with the label container option
-**FR** : Frame (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkFrame.html|GtkFrame]])
-Draw a border around its child, with an optional label.
-shadow	none, in, out, etched-in (default), etched-out
-label	text of the label
-**SB** : Scrolled window (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkScrolledWindow.html|GtkScrolledWindow]])
-Adds scrollbars to its child.
-**AB** : Alignment (based on [[http://developer.gnome.org/doc/API/2.0/gtk/GtkAlignment.html|GtkAlignment]])
-Controls the alignment and size of its child
-options:\\
-''xalign''	Horizontal position of child in available space, value between 0(left) and 1(right), default to .5 (center)\\
-''yalign''	Vertical position of child in available space, value between 0(top) and 1(bottom), default to .5 (center)\\
-''xscale''	If available horizontal space is bigger than needed for the child, how much of it to use for the child. 0.0 means none, 1.0 means all (default :1)\\
-''yscale''	If available vertical space is bigger than needed for the child, how much of it to use for the child. 0.0 means none, 1.0 means all (default :1)
-=====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.
-**HSize/VSize** : Size groups (see [[http://developer.gnome.org/doc/API/2.0/gtk/GtkSizeGroup.html|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 or HSize1 = widget1 widget2''
-**VolumeScroll**:\\
-A unique virtual container (must be the exact name), for all widgets inside, the scroll wheel will modify the volume (unless the scroll event is intercepted, like in a scrollable list)
-=====Properties keys=====
-**Title**:\\
-Set a title for the window instead of the default : songtitle by artist ('%S by %a') (see %-letters)
-	Title = gmusicbrowser playing %S by %a from %l
-**Type**:\\
-A String of letters defining the type(s) of a layout, possible types : B(Browser window), T(Tray window), G(Generic or player window), F(Fullscreen), S(Search), P(Page for use in TabbedLists //experimental//)
-**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, ...)
-**Default**:\\
-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 : pos, size (format is numberxnumber for pos and size), sticky, ontop, below, fullscreen (0 or 1 for these)
-example:
-	Default = Window size=1120x820,sticky=0 HPbig 780 FPane0 page=artist
-**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 action names can be found by running gmusicbrowser with command-line option -listcmd
-**DefaultFocus**:\\
-Name of a widget in the layout.\\
-Set which widget gets the initial focus in the window, will probably only work with very simple widgets and with SongList, SongTree and SimpleSearch for now (let me now if you'd like more)
-**ExtraWidgets**:\\
-Allows the addition of extra widgets to the layout (by options or plugin), for each widget types (only button exist now, I expect to add tab or menuitem in the future) a container can be specified where widgets of this type will be added.
-syntax:
-	ExraWidgets = button container(option1=value1,option2=value)
-the option pack contains packing options as defined above for the container (for example '_' for expand in HBoxes). When the container is a HBox/VBox, the option pos=number can be used to specify at which position the widgets will be inserted. If the added widget s a button, the option relief can be used to specify the button's relief (none, half or normal)
-A layout can be derived from a previously defined layout by adding " based on " followed the name of the reference layout :
-	[layout id] based on another 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 follow the '=')
-=====Widgets list====
-Most widget options are optional, %%''%% means any other value => default behaviour
-All widgets options are using this format :
-	''key1=val1,key2=val2,..., ''
-some still accept the old format:
-	''val1,val2,... ''
-for backward compatibility
-The widgets are listed with this format :
-''WidgetName''	Widget Description
-''optionkey1''	option description and/or possible values
-''optionkey2''	...
-===widgets related to playing song===
-''Album''	Currently playing Album
-''Artist''	Currently playing Artist
-''Comment''	Comment of currently playing song
-''Cover''	Album cover of currently playing song\\
-//''forceratio''//	1 or 0, if 1 always request a square size, useful for tray tip windows as they can't be resized\\
-//''minsize''//	minimum size\\
-//''maxsize''//	maximum size (default is 500)\\
-''ArtistPic''	Artist picture of currently playing song. Same options as Cover. With multiple artists, displays only one picture unless the option multiple was given, which can be set to v (vertical) or h (horizontal)
-''Date''	Year of currently playing song
-''LabelTime''	Position of currently playing song
-''Length''	Length of currently playing song
-''LockAlbum''	Album lock
-''LockArtist''	Artist lock
-''Pos''	Position of currently playing song in the playlist
-''Title''	Currently playing Title
-''Title_by''	Currently playing Title and Artist
-''Scale''	Playing position slider
-''Stars''	Currently playing Rating
-''LabelsIcons''	Icons for currently playing labels for which an icon is defined in ~/.config/gmusicbrowser/icons/ (by a .png or .svg named "label-" followed by the label name.)
-''Visuals''	Eye candy, only with gstreamer
-===Options common to the label widgets===
-The label widgets include : Album, Artist, Comment, Date, Length, LabelTime, Pos, Title, Title_by and Label
-  * 'font' : can e used to change the font, the value is passed to the function [[http://developer.gnome.org/doc/API/2.0/pango/pango-Fonts.html#pango-font-description-from-string|pango_font_description_from_string]].
-  * 'minsize' : if set (it is set by default for Album, Artist, Comment, Title, Title_by), the label will request a minimum width (it can have more if packed with the expand option in a container), if the width is not enough to display the text, the text will scroll on mouseover. The value of the minsize option is the width it will request : the unit is in pixels if followed by a 'p' or in the width of the 'X' character if it is only a number
-  * 'markup' : can be used to re-define the text displayed, you can use %-letters (like %t, %a, ...) for current-song dependent text, and pango markup (like <b>...</b>)for formatting.
-  * 'xalign' : horizontal alignement as a value between 0 (left) and 1 (right), .5 being center
-  * 'yalign' : vertical alignement as a value between 0 (up) and 1 (bottom), .5 being center
-===player buttons widgets===
-''Next''	Next button
-''Play''	Play/Pause button
-''Prev''	Previous button
-''Stop''	Stop button
-''Quit''	Quit button
-''BContext''	Button to open context window
-''Playlist''	Button to open Browser window
-''Pref''	Button to open Settings window
-''ChooseAlbum''	Open a window to select an album
-''OpenQueue''	Open a queue window
-''Fullscreen''	Button to switch to/from fullscreen mode
-''ChooseRandAlbum''	Button to select an album at random, option "action" can be playlist, addplay, insertplay, queue or replacequeue
-The BContext, Playlist 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 to menu, small-toolbar, large-toolbar, button, dialog, dnd (the actual size depends on gtk settings)
-===player indicators widgets===
-''Filter''	Playing filter indicator
-''Queue''	Queue indicator
-''Sort''	Sort mode indicator
-''Vol''	Volume indicator
-'''VolSlider''	Volume slider
-''hide''	hide the value if true (=1)
-''horizontal''	vertical slider if true (=1)
-All indicators can be changed to buttons with the option button=1.
-Size can be changed same as buttons, see above.
-A lot of widgets, in particular 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 :
-	click2=OpenSongProp
-buttons widget also accept the option activate to (re)define the action executed when the button is activated with a mouse click or keyboard
-Also, a lot of widgets, in particular labels, indicators and buttons, can use the option tip, to define a tooltip for the widget. The tip can contains %-letters to display informations on the current song.
-Another common option is cursor, to to change the mouse cursor when it hovers over it (eg : cursor=hand2). See [[http://gtk2-perl.sourceforge.net/doc/pod/Gtk2/Gdk/Cursor.html#enum_Gtk2_Gdk_Cursor|this page]] for a list of cursor names.
-A lot of widgets can also use the hover_layout=ALayoutName option, it causes a window using the ALayoutName layout to popup 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.
-(This feature is still a bit experimental)
-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))
-===Misc. Widgets===
-''AASearch''\\
-//''aa''//	artist or album\\
-//''activate''//	addplay or %%''%%
-''Connections''	List the active connections when in gstreamer-server mode (very rough for now, will be improved some day)
-''Context''	Context view\\
-//''followselection''//	follow songlist selection rather than playing song if true (=1)
-''EditList''	(special)
-''Filler''	empty widget, for use with H/VSize
-''Button''	custom button (other buttons can use these options too)\\
-//''label''//	text\\
-//''stock''//	icon name, see /usr/share/gmusicbrowser/pix/ or Gtk2 Stock-Items or ~/.config/gmusicbrowser/icons/ (without filename extension)
-''Label''	custom label (other labels can use these options too)\\
-//''text''//	label text\\
-//''markup''//	text than can include %-letters and pango markup
-''QueueActions''	combobox to change the queued action
-''SongSearch''
-''TogButton''	Show/Hide other widget(s)\\
-//''icon''//	icon name, see /usr/share/gmusicbrowser/pix/ or Gtk2 Stock-Items or ~/.config/gmusicbrowser/icons/ (without filename extension)\\
-//''label''//	button text\\
-//''widget''//	list of widgets/containers separated by '|'\\
-//''resize''//	String of 'h','v' or '_', one by hidden widget : shrink the window vertically (v) or horizontally (h) when each widget is hidden
-''HSeparator''	Horizontal separator
-''VSeparator''	Vertical separator
-''AddLabelEntry''	Entry to add labels to the current song
-''PlayOrderCombo''	Combo box to change play order, the option reqwidth set the requested width, it defaults to 100, -1 to let it grow, but it can grow much to wide, so it's best to set a minimum width and pack it with the expand option
-''Equalizer''	Equalizer, only active with gstreamer.
-===Songlist widgets===
-When there is more than one SongList/TabbedLists/QueueList 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/QueueList accept the option 'group' to specify which one they interact with, it is only needed when the layout contain more than one SongList/TabbedLists/QueueList.
-**QueueList**	Display queue (and edit it), accept the same options as SongList
-**SongList**\\
-//''hideif''//	'nofilter', 'empty', or %%''%%. Conditions that will make the songlist hide itself or the widgets specified by hidewidget
-//''hidewidget''//	List of widgets separated with '|'. When the hide conditions are met, these widgets will be hidden, by default the songlist is hidden
-//''shrinkonhide''//	String of 'h','v' or '_', one by hidden widget : shrink vertically (v) or horizontally (h) the window when hidden. When multiple widgets are hidden, a direction or no direction (_) can be specified for each widget by using a string of h/v/_
-//''mode''//	playlist or %%''%% : in playlist mode, the songlist and the playlist are synchronized
-//''activate''//	play, queue, playlist, addplay or insertplay. Action when double-clicking on a song : play now, enqueue, set this list as the playlist and play this song, add to playlist, insert in playlist after current position. The action can be followed by a command like this :
-	activate=play&CloseWindow
-//''activateX''//	where X is a mouse button number, defines the action used when the button X is double-clicked
-//''headers''//	off or %%''%%
-//''songypad''//	change the default number of pixels between rows
-//''no_typeahead''//	if true(=1) disable automatic searching when a letter/digit is pressed and the SongList has focus
-**TabbedLists**	Songlists in tabs, can contain playlist, static lists and the queue. Experimental feature : layouts of type 'P' can be opened in TabbedLists (use the layout property key 'stockicon' to set the tab icon)
-**SongTree**	Very customizable Songlist replacement. Some things are still not implemented : drag and dropping columns, playlist, queue or static list mode, moving songs using the EditListButtons widget (arrows button) and type-ahead search. See [[customization:songtree|this wiki page]] for some documentation. These options works : activate activateX headers songxpad songypad
-===widgets related to songlists===
-(filter# is a number between 0-9, 0 is meant for FLock, 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/QueueList they interact with, it is only needed when the layout contain more than one SongList/TabbedLists/QueueList.
-''AABox''	Artist or Album box (name, picture and stats of selected album/artist)\\
-//''aa''//	artist or album
-''EditListButtons''	buttons to remove/move the selected song(s) in the songlist and clear the list\\
-//''small''// :	if true(=1) hide the label of the remove and clear buttons
-''FBox''	advanced search box (set filter#1)
-''FLock''	Lock/unlock : current songlist filter is put in filter#0
-''FPane''	Filter pane\\
-//''nb''//	filter#, filter number to set, the artist/album/genre/date/label/folder pages only show the artist/... for songs matching all filters with a lower number\\
-//''hide''//	hide bottom buttons if true(=1)\\
-//''pages''//	list of pages separated by '|', among filter, list, savedtree, artist, album, genre, date, label, folder, filesys, lastplay, added, modif, rating. Default pages are savedtree artist album genre date label folder added lastplay rating\\
-//''activate''//	play or queue or addplay\\
-//''searchbox''//	if true(=1) add a search box to artist/album,genre,label pages\\
-//''no_typeahead''//	if true(=1) disable automatic searching when a letter/digit is pressed and the FPane has focus
-''PlayFilter''	Button to Play current songlist filter
-''QueueFilter''	Button to Enqueue current songlist filter
-''Refresh''	Refilter songlist
-''ResetFilter''	Reset songlist filter
-''SimpleSearch''	simple search entry, search title/album/artist (set filter#1), the selector icon can be disabled with the option noselector=1. The option activate can be used to set a command to run after enter is pressed.
-''Total''	Total number/length/size of selected/filter/library\\
-//''size''//	change text size, value can be xx-small, x-small, small, medium, large, x-large, xx-large, or see this page\\
-//''format''//	short or long (default)
-===MenuItem widgets (can only be put in a MB/SM)===
-''HistItem''	Filter history (set filter#1)
-''LSortItem''	Sort order for songlist
-''MainMenuItem''	main menu
-''MenuItem''	Custom menu item\\
-//''label''//	text\\
-//''icon''//	name of the icon (same as above)\\
-//''command''//	gmusicbrowser command to execute\\
-//''togglewidget''//	list of widgets/containers separated by '|'\\
-//''resize''//	only with the togglewidget option, see the resize option of the TogButton
-PFilterItem	playing filter menu
-PSortItem	playing sort order
-PlayItem	choose a Filter based on playing title/artist/album/filter (set filter#1) and follow playing songlist option
-QueueItem	queue menu
-SeparatorMenuItem	separator
-====%-letters====
-Some options accept %-letters 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.
-Note that %c and %f are not meant to be used for displaying
-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
-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 main artist or various (determined automatically from all the songs of the album, doesn't use an album_artist tag)
-===== Hints, Bugs, Workarounds =====
-== Bug: Scrambled font in gmusicbrowser widgets ==
-{{:customization:scrambled-font-bug.png|}}
-  * Symptom: Font of some widgets (e.g. Title) gets scrambled when song changes
-  * Affects: gmusicbrowser <= 1.0.1 to >= 1.0.2 (fixed in git branch v1.0.x) and <v1.1.4. (only with gtk >= 2.18)
-  * Reason: Apparently this happens when the Title, Artist, Album widgets are packed into vertical size groups (e.g. ''VSize1 = 40 HBTitle HBArtist HBAlbum'') in the layout file.
-  * Workaround: Do not pack those widgets in a vertical size group. Instead you could use a padding (''20HBTitle 20HBArtist 20HBAlbum'')