NAME

       ttk_vsapi - Define a Microsoft Visual Styles element

SYNOPSIS

       ttk::style element create name vsapi className partId ?stateMap? ?options?
_________________________________________________________________________________________________

DESCRIPTION

       The  vsapi  element  factory  creates  a  new  element  in  the current theme whose visual
       appearance is drawn using the Microsoft Visual Styles API which  is  responsible  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.

       className  and partId are required parameters and specify the Visual Styles class and part
       as given in the Microsoft documentation. The stateMap may be provided to map Ttk states to
       Visual Styles API states (see STATE MAP).

OPTIONS

       Valid options are:

       -padding padding
              Specify  the  element's interior padding.  padding is a list of up to four integers
              specifying the left, top, right and bottom  padding  quantities  respectively.   If
              fewer  than  four elements are specified, bottom defaults to top, right defaults to
              left, and top defaults to left.  In other words, a list of  three  numbers  specify
              the left, vertical, and right padding; a list of two numbers specify the horizontal
              and the vertical padding; a single number specifies the same padding  all  the  way
              around the widget.  This option may not be mixed with any other options.

       -margins padding
              Specifies  the elements exterior padding.  padding is a list of up to four integers
              specifying the left, top, right and bottom padding quantities  respectively.   This
              option may not be mixed with any other options.

       -width width
              Specifies  the height for the element. If this option is set then the Visual Styles
              API will not be queried for the recommended size or the part. If this option is set
              then  -height  should  also  be set. The -width and -height options cannot be mixed
              with the -padding or -margins options.

       -height height
              Specifies the height of the element. See the comments for -width.

STATE MAP

       The stateMap parameter is a list of ttk states and the  corresponding  Visual  Styles  API
       state  value.   This  permits  the  element appearance to respond to changes in the widget
       state such as becoming active or being pressed. The list should be as  described  for  the
       ttk::style map command but note that the last pair in the list should be the default state
       and is typically an empty list and 1. Unfortunately  all  the  Visual  Styles  parts  have
       different  state  values and these must be looked up either in the Microsoft documentation
       or more likely in the header files. The original header to use was tmschema.h, but in more
       recent versions of the Windows Development Kit this is vssym32.h.

       If no stateMap parameter is given there is an implicit default map of {{} 1}

EXAMPLE

       Create  a correctly themed close button by changing the layout of a ttk::button(3tk). This
       uses the WINDOW part  WP_SMALLCLOSEBUTTON  and  as  documented  the  states  CBS_DISABLED,
       CBS_HOT, CBS_NORMAL and CBS_PUSHED are mapped from ttk states.
              ttk::style element create smallclose vsapi WINDOW 19 \
                  {disabled 4 pressed 3 active 2 {} 1}
              ttk::style layout CloseButton {CloseButton.smallclose -sticky news}
              pack [ttk::button .close -style CloseButton]

       Change   the   appearance  of  a  ttk::checkbutton(3tk)  to  use  the  Explorer  pin  part
       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]

SEE ALSO

       ttk::intro(3tk), ttk::widget(3tk), ttk::style(3tk), ttk_image(3tk)

KEYWORDS

       style, theme, appearance, windows