README

   1 =================
   2 Idesk User README  -- Work in progress
   3 =================
   4
   5 Idesk is program that draws desktop icons. Each icon will execute a shell command on a configurable action. The icons can be moved on the desktop by dragging them, and the icons will remember their positions on start-up. Oh yea, forgot there is cool eye-candy.
   6
   7 The icons can either be PNG (.png) or SVG (.svg) files. There are some problems with librsvg's usage of some svg files it seems. Some advanced SVG files _cannot_ be loaded by librsvg. More investigation is needed to see what kind of SVG's work. See note in section 6.
   8
   9 NOTE: No more SVG support. For porting to Imlib2 the SVG was remove.
  10
  11 Dependencies
  12 ---------------
  13
  14 -xft-config   //For Xlib anf X11 support (default)
  15 -imlib2-config //For Imlib2 stuff (default)
  16 -pkg-config    //For libstartup-notification-1.0
  17
  18
  19 Installation
  20 ---------------
  21
  22 Read the INSTALL file.
  23
  24 Config file setup (.ideskrc)
  25 -------------------------------
  26
  27 To use Idesk, you must first setup your config file. Put something like this into into .ideskrc in your home directory:
  28
  29 table Config
  30   FontName: helvetica
  31   FontSize: 12
  32   FontColor: #FFFFFA
  33   FontNameTip: helvetica
  34   FontSizeTip: 9
  35   ForeColorTip: #0000FF
  36   BackColorTip: #FFFFFF
  37   PaddingX: 10
  38   PaddingY: 10
  39   Transparency: 75
  40   HighContrast: true
  41   Locked: false
  42   Shadow: false
  43   ShadowColor: #0006FA
  44   ShadowX: 2
  45   ShadowY: 2
  46   SnapShadow: true
  47   IconSnap: true
  48   SnapWidth: 10
  49   SnapHeight: 10
  50   SnapOrigin: BottomRight
  51   SnapShadowTrans: 300
  52   CaptionOnHover: true
  53   Bold: true
  54   ToolTip.FontSize: 11
  55   ToolTip.FontName: gothic
  56   ToolTip.ForeColor: #0000FF
  57   ToolTip.BackColor: #FFFFFF
  58   ToolTip.CaptionOnHover: true
  59   ToolTip.CaptionPlacement: Right
  60   Background.Delay: 0
  61   Background.Source: /home/aavelar/.idesktop/icons
  62   Background.File: /usr/local/share/gfilerunner/themes/default/search.png
  63   Background.Mode: Mirror
  64   Background.Color: #C2CCFF
  65 end
  66
  67 table Actions
  68   Lock: control right doubleClk
  69   Reload: middle doubleClk
  70   Drag: left hold
  71   EndDrag: left singleClk
  72   Execute[0]: left doubleClk
  73   Execute[1]: right doubleClk
  74 end
  75
  76 -"FontName" is the name Font. Default is Arial.
  77
  78 - "FontSize" is the size Font. Default is 16.
  79
  80 - "ForeColor" is the Foreground color. Default is #000000 (black).
  81
  82 -"ToolTip.FontName" is the name Font for tooltip. Default is Arial.
  83
  84 - "ToolTip.FontSize" is the size Font for the tooltip. Default is 10.
  85
  86 - ToolTip.ForeColor" is the Foreground color for the tooltip window. Default is #FFFFFF (white).
  87
  88 - "ToolTip.BackColor" is the Background color for the tooltip window. Default is #FFFACD.
  89
  90 -"ToolTip.CaptionPlacement" defines the position for Image ToolTip Text. Valid values are: Top, Bottom, Left, Right.
  91
  92 -"ToolTip.CaptionOnHover" is a boolean (true/false) value. Setting it to true will make the icon's tip text appear when the mouse hovers over an icon. False is the default behavior.
  93
  94 -"Locked" is boolean (true/false). Setting it to true disables the dragging movement.
  95
  96 -"Transparency" is between 0 (no glow effect) and 255 (invisible without a mouseover).
  97
  98 -"HighContrast" will draw a border around the text in the opposite colour if it is true.  It will draw it in an arbitary colour if it "#aa00aa", for example.  And it will not draw anything at all if it is set to "false".
  99
 100 -"Shadow" is boolean (true/false). Turning this on will draw a drop shadow of color ShadowColor behind the text. The shadow will be ShadowX pixels right and ShadowY pixels down (negative values will work). Both ShadowX and ShadowY default to 1.
 101
 102 -"Bold" is a boolean (true/false). Setting it to true will make your font bold.
 103
 104 -"Click Delay" is the number of milliseconds that represents a double-click.
 105
 106 -"SingleClick" is a boolean (true/false). Setting it to true makes a single-click execute the command associated with the icon. This also means that it is impossible to drag the icon either.
 107
 108 -"IconSnap" is a boolean (true/false). Setting it to true makes the icons snap to a grid defined by "SnapWidth" and "SnapHeight". The icon will snap to the middle of the rectangle defined by "SnapWidth" and "SnapHeight". So if "SnapWidth" = "SnapHeight" = 100, the center of the icon will by in multiples of 50: (50,50), or (50, 100), or (100, 100), or (250, 350)... You will want to make "SnapWidth" and "SnapHeight" greater than or equal to the size of the picture.
 109
 110 -"SnapWidth" is a positive integer, see description in "IconSnap".
 111 -"SnapHeight" is a positive integer, see description in "IconSnap".
 112
 113 -"SnapOrigin" defines where the snap grip starts from. Valid values are:
 114   TopLeft, TopRight, BottomLeft, BottomRight.
 115
 116 -"SnapShadow" is a boolean (true/false) value. Setting it to true will make a shadow of the icon appear where the icon will snap if the drag was released there. Turn "IconSnap" on and check this out, pretty cool effect.
 117
 118 -"SnapShadowTrans" is a integer between 0 (opaque) and 255 (invisible). It represents the transparency of the SnapShadow
 119
 120
 121 -"CaptionPlacement" defines the position for Image Caption. Valid values are:
 122   Top, Bottom, Left, Right.
 123
 124 -"CaptionOnHover" is a boolean (true/false) value. Setting it to true will make the icon's caption only appear when the mouse hovers over an icon. False is the default behavior.
 125
 126 - "FillStyle" defines the icon appearance when the user gives click him. The icon back to normal form when the user release the mouse button. FillInvert is the default behavior.
 127
 128 - "Background.File" defines the background image for wallpaper. If the path is wrong or the image has a bad format then doesn't put nothing. The image is set to original size only in tile center style (for now). This image remains although  idesk program ins't running. (Default: None).
 129
 130 - "Background.Delay" Set the image change time in minutes format.  (Default: 0 min). Set 0 if you want to leave inactive the changer background system. Max value is 525600 min (forever I think).
 131
 132 - "Background.Source" Let you can define the folder where there are some images. If in the folder there aren't images or the folder didn't exist, then idesk looking for Background.File option.  (Default: None).
 133
 134 - "Background.Mode" Is the display mode for the images, the possible values are: Stretch, Scale, Center, Fit o Mirror).  (Default: Stretch).
 135
 136 - "Background.Color" Just apply when you set Center or Fit options for Background.Mode, the color will be set on corners and borders (Default: None, will be use the current pixmap).
 137
 138 - "CursorOver" defines the mouse cursor type when the mouse hovers over an icon. Valid values are:
 139
 140      num_glyphs
 141      X_cursor
 142      arrow
 143      based_arrow_down
 144      based_arrow_up
 145      boat
 146      bogosity
 147      bottom_left_corner
 148      bottom_right_corner
 149      bottom_side
 150      bottom_tee
 151      box_spiral
 152      center_ptr
 153      circle
 154      clock
 155      coffee_mug
 156      cross
 157      cross_reverse
 158      crosshair
 159      diamond_cross
 160      dot
 161      dotbox
 162      double_arrow
 163      draft_large
 164      draft_small
 165      draped_box
 166      exchange
 167      fleur
 168      gobbler
 169      gumby
 170      hand1
 171      hand2
 172      heart
 173      icon
 174      iron_cross
 175      left_ptr
 176      left_side
 177      left_tee
 178      leftbutton
 179      ll_angle
 180      lr_angle
 181      man
 182      middlebutton
 183      mouse
 184      pencil
 185      pirate
 186      plus
 187      question_arrow
 188      right_ptr
 189      right_side
 190      right_tee
 191      rightbutton
 192      rtl_logo
 193      sailboat
 194      sb_down_arrow
 195      sb_h_double_arrow
 196      sb_left_arrow
 197      sb_right_arrow
 198      sb_up_arrow
 199      sb_v_double_arrow
 200      shuttle
 201      sizing
 202      spider
 203      spraycan
 204      star
 205      target
 206      tcross
 207      top_left_arrow
 208      top_left_corner
 209      top_right_corner
 210      top_side
 211      top_tee
 212      trek
 213      ul_angle
 214      umbrella
 215      ur_angle
 216      watch
 217      xterm
 218
 219
 220 Better Snap Explanation
 221 -----------------------
 222
 223
 224                .          .          .
 225                .          .          .
 226                |__________|__________|_______ . . .
 227                |          |          |
 228                |          |          |
 229            y   |          |          |
 230                |          |          |
 231                |          |          |
 232          [>    |__________|__________|________ . . .
 233          |           x
 234          |
 235          |
 236
 237 This is the bottom left of the desktop (SnapOrigin: BottomLeft)
 238
 239 X represents the snap width
 240 Y represents the snap height
 241 Snap origin only describes which corner of the screen
 242
 243 So basically set snap width to the width of the "box" you want the icon contained in and set snap height to the height of the "box" you want the icon contained in.
 244
 245 The icon will snap to the middle of that box specified by snap width and snap height. You will typically want the width and heihgt to be a bit larger than the width and height of the icons (make the height bigger if you use a caption).
 246
 247 Action Configuration
 248 --------------------
 249
 250 In the Action table 5 different actions can be configured.
 251
 252     Lock:       Disables icon dragging to prevent accidental movement.
 253     Reload:     Reloads all of the config options and gets a new background.
 254     Drag:       Puts the icon in drag mode. Icon follows cursor.
 255     EndDrag:    End the drag mode, icon will be positioned at the cursor.
 256     Execute[i]: Executes the ith icon command. So the Execute[0] action is the
 257                 default action and run Command[0] (in the icon config file),
 258                 Execute[1] runs Command[1] and so forth.
 259
 260 The options for each command are as follows:
 261
 262     <shift> <control> <alt> [Button] [ClickType]
 263     [Button] = left, middle, or right (more than one is allowed)
 264     [ClickType] = singleClk, doubleClk, tripleClk, or hold
 265
 266 Some examples:
 267
 268     The default settings, should be self explanitory.
 269         Lock: right doubleClk
 270         Reload: middle doubleClk
 271         Drag: left hold  <== Drag starts when left button is pressed.
 272         EndDrag: left singleClk <== Drag ends when left button is released.
 273         Execute[0]: left doubleClk
 274
 275     Other examples
 276
 277         Left single click while holding shift on the keyboard
 278         Execute[0]: shift left singleClk
 279
 280         Left double click while holding down the right mouse button.
 281         Execute[0]: left doubleClk right hold
 282
 283         And for those with too many fingers, middle double click while holding
 284         down the left and right mouse buttons, and control, alt, and shift
 285         on the keyboard.
 286         Execute[0]: control shift alt left hold middle doubleClk right hold
 287
 288     Notes:
 289         For the Drag action I reccomend only doing button holds and for the
 290         EndDrag I recommend using single clicks. This way the icon begins
 291         dragging as soon as you press the button and stops dragging as soon
 292         as you release the button. Using other actions should work as expected,
 293         but there are a few small bugs.
 294
 295         If two actions have the same key/button combinations they both will
 296         occur, unless one is the reload action. The reload action always only
 297         happens by itself.
 298
 299
 300 Icon setup (.idesktop/)
 301 --------------------------
 302
 303 To add an icon, you need to first create a .idesktop directory in your home dir and inside that directory, create a file, for example, home.lnk and inside the file put something like this:
 304
 305 table Icon
 306   Caption: Home
 307   CaptionTip: This is my home
 308   Command: nautilus /home/you
 309   Icon: /home/you/.idesktop/home.png
 310   Width: 600
 311   Height: 700
 312   X: 680
 313   Y: 174
 314 end
 315
 316 These are the options for icon file, they should mostly be self-explantory. The Icon option is the graphic file for the icon image (either a png file or a svg file). The Execute[i] action (in .ideskrc) runs the Command[i]. If the Caption field is blank or just one space, then no caption will be created for the icon.
 317
 318 table Icon
 319   Caption: Tux
 320   CaptionTip: Linux rocks
 321   Icon: /home/you/icons/tux2.svg
 322   Width: 600
 323   Height: 700
 324   X: 680
 325   Y: 174
 326   Command[0]: echo 'Linux rocks!'
 327 end
 328
 329 Default Usage
 330 ----------------
 331
 332 - Double click with the first mouse button will run the command.
 333 - When you click the icon change its appearance (depend the fill style).
 334 - Click and drag with the first mouse button moves the icon (if not locked).
 335 - Double-click with the middle mouse button reloads the icons and regenerates
 336   background. Useful after changing wallpapers to clear graphical artifacts.
 337 - Double-click with the right mouse button to toggle the lock state. The
 338   state will be saved in the config file, so it will be remembered next startup.
 339
 340 Bugs
 341 -------
 342
 343 Email the developers if you find bugs.