docs/WindowStyle_proposal.txt

   1 (Feel free to change this file as things get done)
   2
   3 Proposal for changing the way styles are done enabling per window styles
   4 ========================================================================
   5
   6 The final objective of this proposal is to have a WindowStyle command
   7 that understands all the current Style command options but operates on a
   8 single window.
   9
  10 Minor objectives are:
  11 *) The Style command would share the same pattern matching as the ThisWindow
  12 command, any enhancements (e.g. "Class==XXX") will apply to both.
  13 *) Remove the style list management and replace it by reusing the
  14 function list management code (some additions will have to be provided to
  15 allow removing lines from a function)
  16 *) Simplify some commands (e.g. Sticky) to be a wrapper to a WindowStyle
  17 command
  18
  19 WindowStyle Command usage:
  20
  21   WindowStyle <flag> <setting>
  22   <setting> is On/Off, True/False, for on/off flags
  23     (flag prefix '!' may be used instead of setting Off, like !Sticky)
  24   <setting> is number for numeric flags
  25   <setting> is a string for all other types of flag
  26   Not supplying setting is equivalent to "True" for binary flags, 0 for
  27   numeric flags, "" for others.
  28
  29   on/off flags: IconWindow, Title, TitleAtTop, StippledTitle, ResizeHandles,
  30   WindowListSkip, CirculateSkip, Sticky, StartIconic etc.
  31
  32   numeric flags: BorderWidth, StartsOnDesk, StartsOnPage etc.
  33
  34   string flags: Icon, MiniIcon etc.
  35
  36 (Note that these aren't exact copies of the style flags e.g "Style
  37 Slippery" is "WindowStyle Sticky Off". This should make it easier to
  38 write the WindowStyle command at the expense of complicating the final
  39 Style command replacement)
  40
  41 Doing all this in one go will probably introduce a lot of bugs for a
  42 long time so I'm proposing a step by step approach to make it less
  43 traumatic:
  44
  45 *) Fill out the above usage so we can agree on the complete syntax
  46 before we start coding
  47
  48 *) Create a new style flag: X with on/off states.
  49
  50 *) Modify FvwmIdent to show the X flag. (or make it visible on the title
  51 somehow)
  52
  53 *) Write a WindowStyle command that only takes two args: X On/Off that
  54 sets/clears the X flag on the current window.
  55
  56 *) Test it with "Pick WindowStyle X On" and "All WindowStyle X Off"
  57
  58 *) Write a SetOneStyle command that is effectively
  59    AddToFunc SetOneStyle
  60    + I AddToFunc StyleFunction I ThisWindow ($0) WindowStyle $1 $2
  61    + I All StyleFunction
  62
  63 *) Test it with "SetOneStyle <style-pattern> X On" etc
  64
  65 *) Write a DumpFunction command to print out StyleFunction
  66
  67 *) Make sure StyleFunction looks like:
  68    + I ThisWindow (<style pattern>) WindowStyle X On
  69
  70 *) Rename the Style command to OldStyle
  71
  72 *) Write a new Style command:
  73    if ($2 != "X") {
  74      OldStyle $*
  75    } else {
  76      SetOneStyle $*
  77    }
  78
  79 *) Check that "Style <pattern> X On/Off" updates the X flag
  80
  81 *) At the point where styles are applied to new windows add a call to
  82 StyleFunction tmp_win pointing to the new window.
  83
  84 *) Test that new windows get the correct setting of the X flag.
  85
  86 *) Modify the SetOneStyle command so that it deletes the appropriate
  87 lines from StyleFunction before adding to it.  Appropriate means any
  88 lines that affect this flag with patterns that are the same or a subset
  89 of the calling pattern.
  90
  91 *) Check that StyleFunction behaves as it should. Repeated identical
  92 Style commands should leave StyleFunction unchanged. It should never
  93 have duplicate lines. Any flag should only be mentioned once per
  94 pattern. Patterns for the same flag should get more specific, they
  95 should never get less specific.
  96
  97 *) Modify DestroyStyle to be:
  98    if ($2 != "X") {
  99      OldDestroyStyle $*
 100    } else {
 101      DestroyFromStyleFunction $*
 102    }
 103 DestroyFromStyleFunction should share code with SetOneStyle to delete
 104 the appropriate lines from StyleFunction.
 105
 106 *) Check DestroyStyle modifies StyleFunction correctly with various
 107 sub/superset patterns.
 108
 109 *) Repeat the above for the Sticky flag. WindowStyle Sticky should not
 110 do the redraw, it should set the sticky flag and the flag to show that
 111 UpdateStyles should do the redraw if necessary. (just like the OldStyle
 112 command does)
 113
 114 *) Check that a sequence of sticky/on-off in a function don't cause
 115 multiple redraws, should be zero or one.
 116
 117 *) Rewrite the Stick command to call WindowStyle.
 118
 119 *) Rewrite the Style command to handle comma separated lists:
 120    pattern = $1
 121    for (flag, setting) in remaining args {
 122      if (flag != Sticky) {
 123        Oldstyle pattern flag setting
 124      } else {
 125        SetOneStyle pattern flag setting
 126      }
 127    }
 128
 129 *) Check existing config files behave the same.
 130
 131 *) Repeat for a numeric style flag e.g. BorderWidth
 132
 133 *) repeat for a string style flag e.g. MiniIcon
 134
 135 *) Repeat for all the other style flags. Sounds simple but will make the
 136 OldStyle/SetOneStyle test very big until it's all over. This is the
 137 tedious, soul-destroying part. Hopefully we can take it in turns. Is it
 138 possible to arrange the files so that several flags can be worked on by
 139 different people without too many CVS conflicts?
 140
 141 *) Remove the OldStyle and OldDestroyStyle commands. DestroyStyle should
 142 just be:
 143    DestroyFromStyleFunction $*
 144 Style should just be:
 145    pattern = $1
 146    for (flag, setting) in remaining args {
 147      SetOneStyle pattern flag setting
 148    }
 149
 150 *) Document each new arg that WindowStyle understands
 151
 152 *) Rewrite a whole bunch of commands to just call WindowStyle e.g.
 153 Shade, Iconify, Layer. Document these as "to be deleted in the future".
 154
 155 *) Change the style pattern syntax to allow type=pattern where type is
 156 one of name/icon/class/resource. I'm not sure what to do about "Style
 157 Class=*" followed by "Style *" or vice versa, any ideas? Maybe "Style *"
 158 should produce four "Style type=*" commands?
 159
 160 *) Change AddTo/DestroyFunc to treat StyleFunction as readonly so users
 161 can't trash it (have to use the Style command to change StyleFunction)
 162
 163 *) Remove all trace of the X flag
 164
 165 *) Change the name of StyleFunction to some obscure unlikely name
 166 (optional)
 167