Provide a visual-styles API element engine to permit scripts to create

any available windows xp/vista element. Plus basic tests.

1 files changed, 83 insertions, 0 deletions

diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n
new file mode 100644
index 0000000..8bd40d1
--- /dev/null
+++ b/doc/ttk_vsapi.n
@@ -0,0 +1,83 @@
+'\" -*- nroff -*-
+'\" Copyright (c) 2008 Pat Thoyts
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: ttk_vsapi.n,v 1.1 2008/04/08 23:30:45 patthoyts Exp $
+'\" 
+.so man.macros
+.TH ttk::vsapi n 8.5 Tk "Tk Themed Widget"
+.BS
+.SH NAME
+ttk::vsapi \- Define a Microsoft Visual Styles element
+.SH SYNOPSIS
+\fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR
+\fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR?
+.BE
+.SH DESCRIPTION
+The \fIvsapi\fR element factory creates a new element
+in the current theme whose visual appearance is drawn using the
+Microsoft Visual Styles API which is reponsible for the themed styles
+on Windows XP and Vista. This factory permits any of the Visual
+Styles parts to be declared as ttk elements that can then be
+included in a style layout to modify the appearance of ttk widgets.
+.PP
+\fIclassName\fR and \fIpartId\fR are required parameters and specify
+the Visual Styles class and part as given in the Microsoft
+documentation. The \fIstateMap\fR may be provided to map ttk states to
+Visual Styles API states (see \fBSTATE MAP\fR).
+.SH "OPTIONS"
+Valid \fIoptions\fR are:
+.TP
+\fB\-padding\fR \fIpadding\fR
+Specify the element's interior padding.
+\fIpadding\fR is a list of up to four integers specifying
+the left, top, right and bottom borders respectively. This option
+cannot be mixed with any other options.
+.TP
+\fB\-margins\fR \fIpadding\fR
+Specifies the elements exterior padding. The \fIpadding\fR is as
+described for the \fI-padding\fR option. This option may not be mixed
+with any other options.
+.TP
+\fB\-width\fR \fIwidth\fR
+Specifies the height for the element. If this option is set then
+the Visual Styles API will not be queried for the recommended
+size. If this option is set then \fI-height\fR should also be set.
+The \fI-width\fR and \fI-height\fR options cannot be mixed with
+the \fI-padding\fR or \fI-margins\fR options.
+.TP
+\fB\-height\fR \fIheight\fR
+Specifies the height of the element. See the comments for \fI-width\fR.
+.SH "STATE MAP"
+The \fIstateMap\fR parameter is a list of ttk states and the
+corresponding Visual Styles API state value.
+This permits the element appearence to respond to changes in the
+widget state such as becoming active or being pressed. The list should
+be as described for the \fBttk::style map\fR command but note that the
+last pair in the list should be the default state and is typically and
+empty list and 1.
+.PP
+If no \fIstateMap\fR parameter is given there is an implicit default
+\fIstateMap\fR of {{} 1}
+.SH "EXAMPLE"
+Change the appearence of a ttk::checkbutton to use the Explorer pin
+part.
+.CS
+# EXPLORERBAR EBP_HEADERPIN
+ttk::style element create pin vsapi EXPLORERBAR 3 {
+    {pressed !selected} 3
+    {active !selected} 2
+    {pressed selected} 6
+    {active selected} 5
+    {selected} 4
+    {} 1
+}
+ttk::style layout Explorer.Pin {Explorer.Pin.pin -sticky news}
+pack [ttk::checkbutton .pin -style Explorer.Pin]
+.CE
+.SH "SEE ALSO"
+ttk::intro(n), ttk::widget(n), ttk::style(n), ttk::image(n)
+.SH "KEYWORDS"
+style, theme, appearance, windows