Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
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:// | ||
+ | |||
Very rough and incomplete draft, better than nothing | 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 " | ||
+ | |||
+ | 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/ | ||
====== General syntax ====== | ====== General syntax ====== | ||
+ | These definitions can be put in any layout file, ie : a .layout text file in ~/ | ||
{Group mygroupid} | {Group mygroupid} | ||
Line 8: | Line 25: | ||
object1_name : type(opt1=val1, | object1_name : type(opt1=val1, | ||
object2_name : type(opt1=val1, | object2_name : type(opt1=val1, | ||
+ | option1_name : type(opt1=val1, | ||
or | or | ||
Line 15: | Line 33: | ||
object1_name : type(opt1=val1, | object1_name : type(opt1=val1, | ||
object2_name : type(opt1=val1, | object2_name : type(opt1=val1, | ||
+ | |||
+ | Examples can be seen in the ' | ||
+ | |||
====== Groups ====== | ====== Groups ====== | ||
Line 25: | Line 46: | ||
* vcollapse defines the height that will be given to the group in collapsed mode | * 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 | 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 ====== | ====== Columns ====== | ||
Line 37: | Line 60: | ||
* hreq : expression evaluated at column initialization, | * hreq : expression evaluated at column initialization, | ||
all options are optional except title | all options are optional except title | ||
+ | |||
====== Objects ====== | ====== Objects ====== | ||
Line 43: | Line 67: | ||
All objects options, except " | All objects options, except " | ||
- | Some of the options may also be evaluated at group/ | + | Some of the options may also be evaluated at group/ |
+ | |||
+ | Most options have a reasonable default value, they also compute some other values that can be used, for example text/ | ||
- | ===== 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 ===== | ===== align/pack objects and their options ===== | ||
- | Apart from blalign | + | 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. | 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 | * xpack x pad | ||
Line 62: | Line 82: | ||
* blalign y ref | * 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 : '' | ||
- | ===== generic | + | xalign and yalign are used to align objects together, for example, '' |
- | 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/ |
- | xpad, ypad and pad : padding around the object, xpad and ypad default to the value of pad | + | example : '' |
- | xalign and yalign : value between 0 (left/top) and 1 (right/ | + | |
- | hide : if true the object is hidden (=> width and height equal to 0) | + | ===== drawn objects |
+ | |||
+ | * 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 | ||
+ | |||
+ | common options : | ||
+ | * x and y : x and y position, default to 0. if negative, the value is added to $_w or $_h | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
==== text ==== | ==== text ==== | ||
draws 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:// |
* 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 ) | * 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/ | * h and w default to the the height/ | ||
Line 81: | Line 117: | ||
* aakey : artist or album name | * aakey : artist or album name | ||
* picsize : size in pixels, the picture will be resized to fit, respecting ratio | * picsize : size in pixels, the picture will be resized to fit, respecting ratio | ||
- | * picnb : //(will be renamed)// | + | * aanb : artist number when multiple artist |
==== picture ==== | ==== picture ==== | ||
- | draws a picture, can be cropped and resized | + | draws a picture, can be cropped and resized |
* file : path and filename, if the path is relative, look in ~/ | * file : path and filename, if the path is relative, look in ~/ | ||
- | * resize : if ' | + | * resize : (optional) |
- | * crop : option to crop the picture read (FIXME document) | + | * crop : (optional) |
==== icon ==== | ==== icon ==== | ||
draws an icon or multiple icons | draws an icon or multiple icons | ||
* size : icon size, one of ' | * size : icon size, one of ' | ||
- | * 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 : '' |
==== rect ==== | ==== rect ==== | ||
- | draws a rectangle at x,y of width w and height h, filled if " | + | draws a rectangle at x,y of width w and height h, filled if " |
==== line ==== | ==== line ==== | ||
draws a line from x1,y1 to x2,y2 with color " | draws a line from x1,y1 to x2,y2 with color " | ||
+ | ===== 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=' | ||
+ | |||
+ | * type is one of OptionText, OptionColor, | ||
+ | * name is the name that will be displayed in the GUI, use option1_name by default. | ||
+ | * OptionNumber needs a few parameters : min, | ||
+ | * OptionCombo possible values are defined by the parameter list, ' | ||
+ | |||
+ | example : | ||
+ | mytext : OptionText(default=' | ||
+ | text1: text(text=mytext) | ||
+ | will allow the user to change the text that the object ' | ||
+ | |||
+ | more complex example : | ||
+ | mytext | ||
+ | mycolor : OptionColor(default=' | ||
+ | myfont | ||
+ | myhide | ||
+ | title: text( markup='< | ||
Line 105: | Line 162: | ||
**(not finished, lots of variable and functions to add)** \\ | **(not finished, lots of variable and functions to add)** \\ | ||
They consist of " | They consist of " | ||
- | 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 " | + | 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 " |
+ | Values between [ ] will create an array reference. | ||
operators are : != == <= >= - + . % * / < > && || x eq lt gt cmp le ge ne or xor and , \\ | 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 : '' |
+ | * 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: '' | ||
+ | * 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(' | ||
+ | currently allowed perl functions (more to come) : ucfirst uc lc abs int sprintf substr length index join warn \\ | ||
- | example: | + | examples: |
- | 'year is '.if(%year> | + | 'year is '.if($year> |
- | + | 4 kinds of variable : | |
- | 3 kinds of variable : | + | |
* $name : song/group variables | * $name : song/group variables | ||
- | * for columns : title | + | * for columns : title |
- | * for groups title year (more will be added) | + | * for groups |
Line 127: | Line 191: | ||
* $_h : total height | * $_h : total height | ||
* $_expanded : if the group is expanded or not | * $_expanded : if the group is expanded or not | ||
- | * $_state : state of the row, can be selected, active or normal. | + | * $_state : state of the row, can be selected, active or normal. |
+ | * $_depth : number of groups " | ||
+ | * $_odd : true if the row is odd-numbered | ||
+ | |||
+ | * name:option : the value of the object option/ | ||
- | * name:option : the value of the object option/property, this delays | + | * name : options |
- | example | + | * playmarkup : string that can be inserted in a span property |
+ | * ypad and xpad : default space between rows and columns | ||