Differences

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

--- customization:songtree [2007/09/08 04:03] – created squentin
+++ customization:songtree [2022/05/23 01:30] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+This page describe how to customize the SongTree, a new widget introduced in version 0.962 \\
+An example of a SongTree can be seen in this [[http://gmusicbrowser.org/screenshots/songtree_example.png|screenshot]].
 Very rough and incomplete draft, better than nothing
+====== Overview ======
+===== Groups =====
+In a SongTree, the songs are grouped together when they share a common tag (example : same album). Groups can be in turn grouped together (example : same artist).
+Groups appearances are customizable by "skins". A skin defines how much space is put around a group of songs by the options head, tail, left, and right. In addition the option vmin defines a minimum height that the group will have, and the option vcollapse defines the height of the group when it is collapsed (ie : its songs or inner groups are hidden). The width of a group is not controllable by the skin, it depends on the width of the displayed columns and of the left and right option of its inner groups.
+All groups of a level share the same values for these six options (head, tail, left, right, vmin, vcollapse), they are evaluated only once, after the grouping configuration is changed.
+The skin also defines objects, that will be drawn around the songs/inner groups.
+===== Columns =====
+The columns in a SongTree are also customizable in much the same way as groups. But instead of the head/tail/left/right/vmin/vcollapse options, columns have the hreq option that defines the minimum height that the column wants for its rows.
 ====== General syntax ======
+These definitions can be put in any layout file, ie : a .layout text file in ~/.gmusicbrowser/layouts/. The use {} instead of [] to differentiate them from layouts definitions.
   {Group mygroupid}
@@ Line 8: / Line 25: @@
   object1_name : type(opt1=val1,opt2=val2)
   object2_name : type(opt1=val1,opt2=val2)
+  option1_name : type(opt1=val1,opt2=val2)
 or
@@ Line 15: / Line 33: @@
   object1_name : type(opt1=val1,opt2=val2)
   object2_name : type(opt1=val1,opt2=val2)
+Examples can be seen in the 'layouts' file of the current devel version.
 ====== Groups ======
@@ Line 25: / Line 46: @@
   * vcollapse defines the height that will be given to the group in collapsed mode
 all 6 values default to 0, they are expression evaluated at group initialization
+  * title : name used in the grouping edition dialog, default to NameOfTheSkin
 ====== Columns ======
@@ Line 37: / Line 60: @@
   * hreq : expression evaluated at column initialization, set the required row height for this column, the actual row height will be the maximum of all the columns requested heights
 all options are optional except title
 ====== Objects ======
@@ Line 43: / Line 67: @@
 All objects options, except "children", are expressions evaluated before drawing
-Some of the options may also be evaluated at group/column initialization if they are needed (to evaluate head,... for groups and hreq and baseline calculation for columns). At initialization if option "init_name" exists it will be used instead of option "name". For example : the height of a text with markup='<big>$title</big>' won't be correctly computed at init because $title will be an empty string. Using init_markup='<big>anything</big>' will correct this.
+Some of the options may also be evaluated at group/column initialization if they are needed (to evaluate head,... for groups and hreq and baseline calculation for columns). At initialization if option "init_name" exists it will be used instead of option "name". For example : the height of a text with ''markup='<big>'.pesc($title).'</big>''' won't be correctly computed at init because $title (and pesc($title)) will be an empty string. Using init_markup='<big>anything</big>' will correct this.
+Most options have a reasonable default value, they also compute some other values that can be used, for example text/aapic/picture/icon have the values xd, yd, wd, hd wich are the position and size where the actual drawing will be, taking into account the padding and the alignement.
-===== drawn objects and their options =====
-  * text :		x y w h markup text rotate	hide xpad ypad pad xalign yalign
-  * aapic :		picsize aa aakey picnb		hide xpad ypad pad xalign yalign
-  * picture :		x y w h file resize crop	hide xpad ypad pad xalign yalign
-  * icon :		x y w h size icon		hide xpad ypad pad xalign yalign
-  * rect :		x y w h color filled		hide
-  * line :		x1 y1 x2 y2 color		hide
 ===== align/pack objects and their options =====
-Apart from blalign (align the base line of text elements), they are for convenience only as the same result can be achieved without them.
+Apart from blalign, they are for convenience only as the same result can be achieved without them.
 they have a special option : children, which contains a |-separated list of objects. This option is a constant string, it is not evaluated.
   * xpack		x pad
@@ Line 62: / Line 82: @@
   * blalign		y ref
+xpack and ypack are used to pack objects horizontally or vertically, start at x, and separated by a padding of pad pixels.
+example : ''xpack(x=5,pad=2,children=text1|icon1)''
-===== generic objects options =====
+xalign and yalign are used to align objects together, for example, ''xalign(x=100,align=1,children=text1|text2)'' will compute a x value for text1 and text2 such that they are right-aligned at x=100, align=.5 would center them around x=100. The option ref is by default equal to align, it defines where is the x. For example ''align(x=100,align=1,ref=0,children=text1|text2)'' will right-align text1 and text2 but rather than ending at x=100 as before, the wider will begin at x=100.
-x and y : x and y position, default to 0. if negative, the value is added to $_w or $_h
-w and h : width and height
+blalign is used to align text object so that their baseline is align even if the text have different font/size.
-xpad, ypad and pad : padding around the object, xpad and ypad default to the value of pad
+example : ''blalign(y=10,children=text1|text2)'' will compute a y for text1 and text2 so that their baseline are aligned, the heighest text will have a y of 10. The option ref default to 0, it defines the reference point of the y value, ref=0 means the top of the string, ref=1 means the bottom.
-xalign and yalign : value between 0 (left/top) and 1 (right/bottom), used to align the object in its allocated space (h and w)
-hide : if true the object is hidden (=> width and height equal to 0)
+===== drawn objects and their options =====
+  * text :		x y w h markup text rotate	hide xpad ypad pad xalign yalign
+  * aapic :		picsize aa aakey picnb		hide xpad ypad pad xalign yalign
+  * picture :		x y w h file resize crop	hide xpad ypad pad xalign yalign
+  * icon :		x y w h size icon		hide xpad ypad pad xalign yalign
+  * rect :		x y w h color filled width	hide
+  * line :		x1 y1 x2 y2 color width	        hide
+common options :
+  * x and y : x and y position, default to 0. if negative, the value is added to $_w or $_h
+  * w and h : width and height
+  * xpad, ypad and pad : padding around the object, xpad and ypad default to the value of pad
+  * xalign and yalign : value between 0 (left/top) and 1 (right/bottom), used to align the object in its allocated space (h and w)
+  * hide : if true the object is hidden (=> width and height equal to 0)
 ==== text ====
 draws text
-  * text OR markup : plain text or pango markup to draw, in the markup option, variable strings should be escaped using the pesc() function.
+  * text OR markup : plain text or [[http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html|pango markup]] to draw, in the markup option, variable strings should be escaped using the pesc() function.
   * rotate : can be 0, 90, 180 or 270 (ignored except with very recent Gtk2 bindings (>1.146 (stable branch) or >1.154 (unstable branch) due to a bug )
   * h and w default to the the height/width needed to draw the text +2*xpad or +2*ypad
@@ Line 81: / Line 117: @@
   * aakey : artist or album name
   * picsize : size in pixels, the picture will be resized to fit, respecting ratio
-  * picnb : //(will be renamed)// artist number when multiple artist
+  * aanb : artist number when multiple artist
 ==== picture ====
-draws a picture, can be cropped and resized (not cached yet)
+draws a picture, can be cropped and resized
   * file : path and filename, if the path is relative, look in ~/.gmusicbrowser/layouts/
-  * resize : if 's' resize to fill the space allocated (by w and h) (more possible values FIXME document)
+  * resize : (optional) if 's' resize to fill the space allocated (by w and h) (more possible values FIXME document)
-  * crop : option to crop the picture read (FIXME document)
+  * crop : (optional) option to crop the picture read, format : x_y_w_h
 ==== icon ====
 draws an icon or multiple icons
   * size : icon size, one of 'menu' (default), 'small_toolbar', 'large-toolbar', 'button' 'dnd' 'dialog'. these sizes are defined by the gtk options
-  * icon : icon name, can be an array ref containing multiple icon names (only by using $labelicons for now)
+  * icon : icon name, can be an array ref containing multiple icon names (example : ''['gtk-media-play','gtk-media-stop']'' )
 ==== rect ====
-draws a rectangle at x,y of width w and height h, filled if "filled" is true, with the color "color" which can be a color name or hexadecimal (#000 or #000000)
+draws a rectangle at x,y of width w and height h, filled if "filled" is true, with the color "color" which can be a color name or hexadecimal (#000 or #000000), the line width is width, 1 by default
 ==== line ====
 draws a line from x1,y1 to x2,y2 with color "color" (same as above)
+===== user-editable group settings =====
+Groups can define some settings that can easily be changed by user, for example for choosing a color, font, text ...
+There are different types of settings, the type only affect the interface that the user will use to edit it.
+the syntax is :
+  option1_name : type(default='default value',name='an optional name',opt1=val1)
+  * type is one of OptionText, OptionColor, OptionFont, OptionBoolean, OptionNumber, OptionCombo.
+  * name is the name that will be displayed in the GUI, use option1_name by default.
+  * OptionNumber needs a few parameters : min,max,step,digits. min is the minimum value, max is the maximum value, step is increment/decrement used when editing, digits is the number of decimals.
+  * OptionCombo possible values are defined by the parameter list, '|' is used as a separator. example list='value1|value2|value3 with \' & \| characters|value4'
+example :
+  mytext : OptionText(default='some text',name='name of the option')
+  text1: text(text=mytext)
+will allow the user to change the text that the object 'text1' will display.
+more complex example :
+  mytext  : OptionText(default='some text',name='some text')
+  mycolor : OptionColor(default='blue',name='Title color')
+  myfont  : OptionFont(default='Arial 20',name='font')
+  myhide  : OptionBoolean(default=0,name='hide')
+  title: text( markup='<span font_desc="'.myfont.'" foreground="'.mycolor.'">'.pesc(mytext).'</span>', hide=myhide)
@@ Line 105: / Line 162: @@
 **(not finished, lots of variable and functions to add)** \\
 They consist of "values" separated by "operators". \\
-Values can be one of the 3 kinds of variables, a function, a numerical value, or a string. Variables and functions can be preceded by -(negative) or ! (not). Functions are followed by a list of ,-separated arguments between "()". Strings are delimited by simple quotes ('), there is no variable interpolation for now.
+Values can be one of the 4 kinds of variables, a function, a numerical value, or a string. Variables and functions can be preceded by -(negative) or ! (not). Functions are followed by a list of ,-separated arguments between "()". Strings are delimited by simple quotes ('), there is no variable interpolation for now.
+Values between [ ] will create an array reference.
 operators are : != == <= >= - + . % * / < > && || x eq lt gt cmp le ge ne or xor and , \\
-functions : if pesc max min not \\
+functions :
-currently allowed perl functions (more to come) : ucfirst uc lc \\
+  * if : if the first argument is true, return the second, else the third. If more than three arguments, this is repeated, ie : ''if($x>10, 'x is >10', $x>5, 'x is >5', 'x is <= 5')''
+  * pesc : escape its argument so it can be used in a pango markup
+  * playmarkup : (for columns) if the song is the playing song, return its argument between the playing markup, else just return the argument. ie: ''playmarkup('a_markup')'' will be transformed to '''<span weight="bold">a_markup</span>''' if the song is currently playing. Equivalent to ''if($playing,'<span '.playmarkup.'a_markup</span>','a_markup')''
+  * max & min : return the maximum or minimum of the arguments
+  * not : return the negation of its argument, same as !
+  * average : return the average of its arguments (not rounded, may change)
+  * formattime : to format time, the first parameter is the standard time format string, the second parameter is the number of seconds since epoch and the third optional parameter is the value when the number of seconds is 0, which is the value of $lastplay_ when the song has never been played, example : formattime('%F',$lastplay_,'never')
+currently allowed perl functions (more to come) : ucfirst uc lc abs int sprintf substr length index join warn \\
-example:
+examples:
-  'year is '.if(%year>2000,'after 2000 : ', 'before 2000 :').$year
+  'year is '.if($year>2000,'after 2000 : ', 'before 2000 :').$year
+ kinds of variable :
- kinds of variable :
   * $name : song/group variables
-    * for columns : title   artist  album  date  year  track  disc  comment  playcount  ufile  upath  version  rating  channel  samprate  bitrate  filetype  size  genre  label  lastplay  added  modif  length  progress  playing  playicon  labelicons
+    * for columns : title   artist  album  date  year  track  disc  comment compilation  playcount  ufile  upath  version  rating  channel  samprate  bitrate  filetype  size  genre  label  lastplay  added  modif  length  progress  playing  playicon  labelicons queued length_ lastplay_ added_ modif_ \\ length_ lastplay_ added_ modif_ are raw values in seconds that can be formatted differently using the function formattime or sprintf
-    * for groups title year (more will be added)
+    * for groups : title year length artist album disc genres labels nbsongs (more will be added)
@@ Line 127: / Line 191: @@
     * $_h : total height
     * $_expanded : if the group is expanded or not
-    * $_state : state of the row, can be selected, active or normal. Has Groups can't be selected yet, it's only useful for columns
+    * $_state : state of the row, can be selected, active or normal. As Groups can't be selected yet, it's only useful for columns
+    * $_depth : number of groups "above" the current one. ie : if the songs are grouped by artist then album, the artist group will have a depth of 0, and the album group will have a depth of 1.
+    * $_odd : true if the row is odd-numbered
+  * name:option : the value of the object option/property, this delays the evaluation of the expression until that object option/property has been evaluated. \\ e.g.  title:h is the height of the title object
-  * name:option : the value of the object option/property, this delays the evaluation of the expression until that object option/property has been evaluated
+  * name : options of the column/group, will be user-editable, currently the columns have these predefined options :
-example :  title:h is the height of the title object
+    * playmarkup : string that can be inserted in a span property of a pango markup (default to '''weight="bold"'''), used to set the playing row apart, using the playmarkup function is better in most case
+    * ypad and xpad : default space between rows and columns