<simplesect id="config-autoprops-basic" xreflabel="Basic Autoproperties Syntax"> 
  <title>Basic Autoproperties Syntax</title>

  <para>
    The <filename>~/.pekwm/autoproperties</filename> file follows the
    rules in <xref linkend="config-syntax"/>. This file can become
    rather complicated, but it's also the most powerful of any of
    pekwm's config files.
  </para>

  <para>
    The one important thing to remember is the Property tag.  This
    identifier tells us where to apply properties. It means which
    windows to apply it on. To find out the two terms,
    use <command>xprop WM_CLASS</command> and click on your window.
    Below you'll find a bash/zsh function which will give you the
    correct string for this file.  You can also specify a regexp
    wildcard, such as ".*,opera", which means anything for the first
    word, opera for the second.
  </para>

  <screen>propstring () {
  echo -n 'Property '
  xprop WM_CLASS | sed 's/.*"\(.*\)", "\(.*\)".*/= "\1,\2" {/g'
  echo '}'
}</screen>

  <para>
    Autoproperties have an both an old and new style matching
    clients. The new style was introduced to support using
    configuration template overwriting.
  </para>

  <para>
    In addition with WM_CLASS, pekwm also can identify clients by
    their title string (<command>xprop WM_NAME</command>
    or <command>xprop _NET_WM_NAME</command>).
  </para>

  <screen># New syntax, requires Require { Templates = "True" }
Property = "^dillo,^Dillo,,Dillo: pekwm.org - not just another windowmanager" {
	ApplyOn = "Start New"
	Layer = "OnTop"
}

# Old syntax
Property = "^dillo,^Dillo" {
        Title = "Dillo: pekwm.org - not just another windowmanager"
	ApplyOn = "Start New"
	Layer = "OnTop"
}</screen>

  <para>
    Or by their role (<command>xprop WM_WINDOW_ROLE</command>):
  </para>

  <screen># New syntax, requires Require { Templates = "True" }
Property = "^gaim,^Gaim,preferences" {
	ApplyOn = "New"
	Skip = "Menus"
}

# Old syntax
Property = "^gaim,^Gaim" {
	Role = "preferences"
	ApplyOn = "New"
	Skip = "Menus"
}</screen>

  <para>
    Pekwm can rewrite window titles.  This is done in a separate
    TitleRules section, where one defines properties on which clients
    to use the rewriting and then a regexp rule of what to do to that
    clients title. These rules do not affect the actual WM_NAME
    string. You can use Role and Title keywords to narrow down the
    clients the titlerule applies to. A simple rule that would change
    "Title: this is the title" to "this is the title" looks like
    this:
  </para>

  <screen>TitleRules {
	Property = "^foo,^bar" {
		Rule = "/Title: (.*)/\\1/"
	}
}</screen>

  <para>
    In pekwm, you can make certain windows have their own decoration
    set.  The different decorations are defined in the theme, and they
    are connected to client windows with an autoproperty. These
    autoproperties reside in their own DecorRules subsection and look
    like this:
  </para>

  <screen>DecorRules {
	Property = "^foo,^bar" {
		Decor = "TERM"
	}
}</screen>

  <para>
    It's also possible to decide the order of applications that start
    in the harbour. As with TitleRules and DecorRules, there is it's
    own separate section for this purpose called Harbour.  Position is
    a signed int and order goes: "1 2 3 0 0 0 -3 -2 -1", and so on.
    That looked cryptic. Worry not. Basically, a Position number of 0
    means the application will be placed in the middle. If the number
    is positive, the application will be placed before the
    zero-positioned applications. If the number is negative, the
    applications will be placed after the zero-position ones. So the
    positive numbered show up first in your harbour, then the zero
    numbered, and after the zeros come the negatively numbered
    applications.  I hope that is clear, the next part is tricky. The
    larger the value of the base number the closer to the zero
    applications they will be. So the smaller the base number the
    closer to the ends of the harbour the application will
    be. Position 1 would be the first application to show up on the
    harbour. And similarly Position -1 would be the last application
    on the harbour. If you have application on the harbour that do not
    match any of the property rules on the Harbour section, they will
    act as if you had given them Position 0. Applications with the
    same Position will show up next to each other in the order they are
    launched. In our example below, obpager will always be placed the
    last on the harbour.
  </para>

  <screen>Harbour {
	Property = "^obpager,^obpager" {
		Position = "-1";
	}
}</screen>

  <para>
    If you want certain autoproperties to be only applied when you are
    on a specific workspace, you can add a workspace section. The
    following example sets an autoproperty that removes the border and
    titlebar from xterm on the second and third workspace. Please keep
    in mind that we start counting with 0.
  </para>
  <screen>Workspace = "1 2" {
    Property = "xterm,XTerm" {
        ApplyOn = "Start New Reload"
        Border = "False"
        Titlebar = "False"
    }
}</screen>

  <para>
    Here's an example <filename>~/.pekwm/autoproperties</filename> file:
  </para>

  <screen>Property = ".*,^xmms" {
	ApplyOn = "Start New"
	Layer = "0"
	Sticky = "True"
}

Property = "^xclock,^XClock" {
	ApplyOn = "Start New"
	FrameGeometry = "100x100+0-0"
	Border = "False"; Titlebar = "False"
	Sticky = "True"
	Layer = "Desktop"
}

Property = "^dillo,^Dillo" {
	ApplyOn = "Start New"
	Group = "browsers" {
		Size = "30"
		Behind = "True"
		Global = "False"
	}
}

TitleRules {
	Property = "^dillo,^Dillo" {
		Rule = "/Dillo: (.*)/\\1 [dillo]/"
	}
	Property = "^opera,^opera" {
		Rule = "/...:... - (.*) - Opera .*/\\1 [opera]/"
	}
}

DecorRules {
	Property = "^.term,^XTerm" {
		Decor = "TERM"
	}
}

Harbour {
	Property = "^obpager,^obpager" {
		Position = "-1"
	}
}</screen>

  <note>
    <formalpara>
      <title>Regular Expressions!</title>

      <para>
	The pekwm autoproperties file uses Regular Expression syntax
	for wildcards.  Regular expressions can be really confusing to
	people with no experience with them. A good rule of thumb is:
	"Anywhere you'd think to use '*', use '.*'". Also, '^' matches
	the beginning of a string, '$' matches the end, and '.' is any
	single character.

        Pekwm has some special flags to that modifies regular
        expression matching. Specifying regular expressions in the
        form /pattern/flags allow flags to be set. The supported flags
        are ! for inverting the match and i for case insensitive
        matches.

        Explaining the syntax of regular expressions goes beyond the scope of
        this documentation. You might want to look at
        <ulink url="http://www.regularexpressions.info/">http://www.regularexpressions.info/</ulink> or
        <ulink url="http://en.wikipedia.org/wiki/Regular_expressions">http://en.wikipedia.org/wiki/Regular_expressions</ulink>.
      </para>
    </formalpara>
  </note>
</simplesect>

