Welcome to the CHICKEN Scheme pasting service

:h5 "bb:property"

:procedure (bb:property WIDGET PROPERTY)
:setter    (set! (bb:property WIDGET PROPERTY) VALUE)

Gets or sets the properties given in :tt "PROPERTY1 ..." (which should be symbols).
Values may also be lists, in that case the values are combined (this only applies to certain properties - see below).

Some properties may be set for individual items of the :tt tree and :tt table widgets.
They are specified in the form :tt '(list WIDGET ITEMID).
:tt ITEMID is either unique item id or one of the symbols:

>ul * :tt root
    * :tt connector
    * :tt leaf
    * :tt branch

In this case the :tt VALUE will be applied either to root node, connector or
all subsequent branches or leaves added to the tree.

:tt width and :tt align properties can be applied to the :tt table widget's columns.

Allowed widget properties are:

>dl

 :dt x

 :dt y

 :dt width

 :dt height
 >dd Position and dimensions (integer). Positions are always relative
     to the container. :tt width property may be set for :tt connector
     item of the :tt tree widget.

 :dt text    >dd The text of a label, button, text-fields or :tt html-view. 
                 Also the title of a window. For the :tt tree widget the value
                 is the label of the subitem. For the :tt table widget one can
                 specify individual cells in the form :tt '(list TABLEWIDGET ROW COLUMN).
                 The negative :tt ROW means column header.

 :dt value   
 :dd { The value of a "range" widget (:tt slider, :tt roller,
  :tt adjuster, :tt counter or :tt dial), in which case it should be a
  number. For :tt check-box and :tt radio-button widgets the value
  should be a boolean. For :tt list widgets, the value is the index of
  the highlighted item, starting from 1. The value of the
  :tt choice-button widget is the index of the selected item. For
  :tt tree widgets, the value is the unique id of the currently
  selected item. The value of the :tt html-view is a current file
  name. }

 :dt box
 >dd The :em {box type}. A box type is one of the symbols
     >list
       > no-box
       > flat-box
       > up-box
       > down-box
       > up-frame
       > down-frame
       > thin-up-box
       > thin-down-box
       > thin-up-frame
       > thin-down-frame
       > engraved-box
       > embossed-box
       > engraved-frame
       > embossed-frame
       > border-box

 :dt callback :dd{ The callback procedure that is invoked when the
                   value of a widget changes. See the :tt when
                   property for more information. For :tt tree widgets
                   one can obtain additional information from
                   properties :tt callback-reason and
                   :tt callback-node. }

 :dt image    >dd An image that should be drawn into the widget. See :tt
                  bb:image for how to load images. You can also set
                  the value :tt image property to a string, which will
                  load any image file with this name
                  automatically. The value may also be a pointer
                  object pointing to a data buffer for a :tt
                  live-image widget. Images may be set for a :tt tree
                  widget items. If subitem is the :tt branch or :tt
                  connector, then :tt VALUE can specify pair of the
                  images: for closed and open state respectively.

 :dt type
 >dd The :em type of a widget. The possible type symbols 
     depend on what kind of widget it applies to:

     >ul
      >li :tt scroll (may be combined)
          >ul
             >li scroll-horizontal
             >li scroll-vertical
             >li scroll-both
             >li scroll-always-on
             >li scroll-horizontal-always
             >li scroll-vertical-always
             >li scroll-both-always
      >li :tt slider
          >ul
             >li vertical-fill-slider
             >li horizontal-fill-slider
             >li vertical-nice-slider
             >li horizontal-nice-slider
      >li :tt dial
          >ul
             >li normal-dial
             >li line-dial
             >li fill-dial
             >li resizable

     (FIXME Jim: Another way to write this list:)

     >list
      > :tt scroll (may be combined)
        >list
                 > scroll-horizontal
                 > scroll-vertical
                 > scroll-both
                 > scroll-always-on
                 > scroll-horizontal-always
                 > scroll-vertical-always
                 > scroll-both-always
      > :tt slider
        >list
                 > vertical-fill-slider
                 > horizontal-fill-slider
                 > vertical-nice-slider
                 > horizontal-nice-slider
      > :tt dial
        >list
                 > normal-dial
                 > line-dial
                 > fill-dial
                 > resizable

     (FIXME Jim: A proposed way to write this list:)

     >list
      * :tt scroll (may be combined)
        >list
         * scroll-horizontal
         * scroll-vertical
         * scroll-both
         * scroll-always-on
         * scroll-horizontal-always
         * scroll-vertical-always
         * scroll-both-always
      * :tt slider
        >list
         * vertical-fill-slider
         * horizontal-fill-slider
         * vertical-nice-slider
         * horizontal-nice-slider
      * :tt dial
        >list
         * normal-dial
         * line-dial
         * fill-dial
         * resizable



 :dt modal     >dd Whether a window is resizable and/or modal.

 :dt direction >dd The direction of a widget, which should be one of the symbols
                   :tt horizontal or :tt vertical.

 :dt color     >dd The background color of a widget. This can either 
                   be a value returned by :tt bb:rgb or one of the following symbols:

                   :(list gray0 dark3 dark2 dark1 light1 light2 light3
                          gray black red green yellow blue magenta cyan
                          dark-red dark-green dark-yellow dark-blue dark-magenta dark-cyan
                          white)

                   The color attribute of a :tt live-image widget designates the number of color channels (1-4).
                   Also is applicable to the :tt connector subitem of the :tt tree widget.

 :dt image-width >dd The width of a :tt live-image widget.

 :dt image-height >dd The height of a :tt live-image widget.

 :dt focus        >dd Whether this widget has the input focus. 
                      Calling :tt bb:property for this property will always return 0
                      (but setting it will change the focus to the target widget).

 :dt spacing      >dd The spacing inside group widgets (in pixels).

 :dt maximum      >dd Maximum value for range widgets.

 :dt minimum      >dd Minimum value for range widgets.

 :dt x-position   >dd X-position for :tt scroll widgets.

 :dt y-position   >dd Y-position for :tt scroll widgets.

 :dt text-color   >dd Text color. Can also be applied to the :tt tree subitems.

 :dt text-size    >dd Text size. Can also be applied to the :tt tree subitems.

 :dt text-font
 >dd Text font, which may be one of the following:

     >list  > helvetica
            > helvetica-bold
            > helvetica-italic
            > helvetica-bold-italic
            > courier
            > courier-bold
            > courier-italic
            > courier-bold-italic
            > times
            > times-bold
            > times-italic
            > times-bold-italic
            > symbol
            > screen
            > screen-bold

     Can be specified for the :tt tree branches and leaves.

 :dt label-color
 >dd Color of a label.

 :dt label-size
 >dd Size of a label.

 :dt label-font
 >dd Font of a label.

 :dt selection-color
 >dd The color of the selection in a text widget or the color of indicators in other widgets.

 :dt position
 >dd The position of the caret in an :tt entry, :tt edit or :tt text-editor widget. Setting the position to :tt -1 will move the caret to the end of the current text.

 :dt mark
 >dd The position of the selection mark in an :tt entry, :tt edit or :tt text-editor widget. The text between the selection mark and the caret is the current selection.

 :dt selection
 >dd The currently selected text in an :tt entry, :tt edit or :tt text-editor widget. When set, the value should be a pair containing start and end position of the selection in the buffer.

 :dt tooltip
 >dd A string that should be displayed, when the mouse hovers over a widget.

 :dt visible
 >dd Whether a widget is visible or not.

 :dt resizable-widget
 >dd The widget in a group, which should be exclusively resizable.

 :dt valid-context
 >dd A flag indicating whether the GL context for a :tt glwindow is already initialized.

 :dt read-only
 >dd If true, an :tt edit or :tt entry widget can not be changed by the user.

 :dt align  >dd The alignment of the widget label. May be combination of the following symbols:

                >list * center
                      * top
                      * bottom
                      * left
                      * right
                      * inside
                      * text-over-image
                      * image-over-text
                      * clip
                      * wrap

 :dt when
 >dd An indicator when a widgets callback should be
     invoked. The default behaviour depends on the type of the
     widget. Possible settings are:

     >dl :dt never    >dd never invoked the callback
         :dt changed  >dd when the widget's value changes
         :dt released >dd when the button or key is released and the value changes
         :dt enter    >dd when the enter key is pressed and the value changes
         :dt always   >dd modifier for :tt released or :tt enter, that indicates 
                          the callback should be invoked, even if the value doesn't change

     The default behaviour is to invoke the callback whenever the value of
     a widget changes, when a :tt window is closed, when :tt glwindow needs
     to be redrawn, or a :tt button or :tt list item has been clicked.

 :dt  handler  :dd{ The callback procedure that is invoked when 
                    the event occurs. The event is passed in a
                    first (and only) argument to the handler. 
                    A event is one of the symbols:

                    :(list
                      no-event push release enter leave drag
                      focus unfocus keydown keyup close move shortcut
                      deactivate activate hide show paste selectionclear 
                      mousewheel dnd-enter dnd-drag dnd-leave 
                      dnd-release unknown)

                    Additional information about event can be obtained with :tt bb:event
                    procedure.  Returning :tt #f from handler indicates that widget is not
                    interested in handling this event. :tt #t means that event was
                    successfully handled. Any other value leads to invoking default
                    handler of this widget.
                      
                    The :tt html-view widget's :tt handler is invoked when user tries to
                    follow the link (which URI is passed as an argument). :tt handler
                    should return either the name of the temporary file or :tt #f and set
                    the :tt text property. }

 :dt callback-reason
 >dd The reason for callback. Available only for :tt tree widget. Valid values are:
     >list 
      * hilighted
      * unhilighted
      * selected
      * unselected
      * opened
      * closed
      * double-click
      * widget-callback
      * moved-node
      * new-node
      * nothing

 :dt callback-node
 >dd The unique id of the node that caused callback. Available only for :tt tree widget.

===== bb:property

(bb:property WIDGET PROPERTY)
(set! (bb:property WIDGET PROPERTY) VALUE)

Gets or sets the properties given in {{PROPERTY1 ...}} (which should be symbols).
Values may also be lists, in that case the values are combined (this only applies to certain properties - see below).

>Some properties may be set for individual items of the {{tree}} and {{table}} widgets.
They are specified in the form {{(list WIDGET ITEMID)}}.
{{ITEMID}} is either unique item id or one of the symbols:

* {{root}}
* {{connector}}
* {{leaf}}
* {{branch}}

In this case the {{VALUE}} will be applied either to root node, connector or
all subsequent branches or leaves added to the tree.

{{width}} and {{align}} properties can be applied to the {{table}} widget's columns.

Allowed widget properties are:

; x :

; y :

; width :

; height : Position and dimensions (integer). Positions are always relative to the container. {{Width}} property may be set for {{connector}} item of the {{tree}} widget.

; text : The text of a label, button, text-fields or {{html-view}}. Also the title of a window. For the {{tree}} widget the value is the label of the subitem. For the {{table}} widget one can specify individual cells in the form {{(list TABLEWIDGET ROW COLUMN)}}. The negative {{ROW}} means column header.

; value : The value of a "range" widget ({{slider}}, {{roller}}, {{adjuster}}, {{counter}} or {{dial}}), in which case it should be a number. For {{check-box}} and {{radio-button}} widgets the value should be a boolean. For {{list}} widgets, the value is the index of the highlighted item, starting from 1. The value of the {{choice-button}} widget is the index of the selected item. For {{tree}} widgets, the value is the unique id of the currently selected item. The value of the {{html-view}} is a current file name.

; box : The ''box type''. A box type is one of the symbols
* no-box
* flat-box
* up-box
* down-box
* up-frame
* down-frame
* thin-up-box
* thin-down-box
* thin-up-frame
* thin-down-frame
* engraved-box
* embossed-box
* engraved-frame
* embossed-frame
* border-box

; callback : The callback procedure that is invoked when the value of a widget changes. See the {{when}} property for more information. For {{tree}} widgets one can obtain additional information from properties {{callback-reason}} and {{callback-node}}.

; image : An image that should be drawn into the widget. See {{bb:image}} for how to load images. You can also set the value {{image}} property to a string, which will load any image file with this name automatically. The value may also be a pointer object pointing to a data buffer for a {{live-image}} widget. Images may be set for a {{tree}} widget items. If subitem is the {{branch}} or {{connector}}, then {{VALUE}} can specify pair of the images: for closed and open state respectively.

; type : The ''type'' of a widget. The possible type symbols depend on what kind of widget it applies to:

scroll:

* scroll-horizontal
* scroll-vertical
* scroll-both
* scroll-always-on
* scroll-horizontal-always
* scroll-vertical-always
* scroll-both-always

(may be combined)

slider:

* vertical-fill-slider
* horizontal-fill-slider
* vertical-nice-slider
* horizontal-nice-slider

dial:

* normal-dial
* line-dial
* fill-dial
* resizable

; modal : Whether a window is resizable and/or modal.

; direction : The direction of a widget, which should be one of the symbols {{horizontal}} or {{vertical}}.

; color : The background color of a widget. This can either be a value returned by {{bb:rgb}} or one of the following symbols:

* gray0
* dark3
* dark2
* dark1
* light1
* light2
* light3
* gray
* black
* red
* green
* yellow
* blue
* magenta
* cyan
* dark-red
* dark-green
* dark-yellow
* dark-blue
* dark-magenta
* dark-cyan
* white

The color attribute of a {{live-image}} widget designates the number of color channels (1-4).
Also is applicable to the {{connector}} subitem of the {{tree}} widget.

; image-width : The width of a {{live-image}} widget.

; image-height : The height of a {{live-image}} widget.

; focus : Whether this widget has the input focus. Calling {{bb:property}} for this property will always return 0 (but setting it will change the focus to the target widget).

; spacing : The spacing inside group widgets (in pixels).

; maximum : Maximum value for range widgets.

; minimum : Minimum value for range widgets.

; x-position : X-position for {{scroll}} widgets.

; y-position : Y-position for {{scroll}} widgets.

; text-color : Text color. Can also be applied to the {{tree}} subitems.

; text-size : Text size. Can also be applied to the {{tree}} subitems.

; text-font : Text font, which may be one of the following:

* helvetica
* helvetica-bold
* helvetica-italic
* helvetica-bold-italic
* courier
* courier-bold
* courier-italic
* courier-bold-italic
* times
* times-bold
* times-italic
* times-bold-italic
* symbol
* screen
* screen-bold

Can be specified for the {{tree}} branches and leaves.

; label-color : Color of a label.

; label-size : Size of a label.

; label-font : Font of a label.

; selection-color : The color of the selection in a text widget or the color of indicators in other widgets.

; position : The position of the caret in an {{entry}}, {{edit}} or {{text-editor}} widget. Setting the position to {{-1}} will move the caret to the end of the current text.

; mark : The position of the selection mark in an {{entry}}, {{edit}} or {{text-editor}} widget. The text between the selection mark and the caret is the current selection.

; selection : The currently selected text in an {{entry}}, {{edit}} or {{text-editor}} widget. When set, the value should be a pair containing start and end position of the selection in the buffer.

; tooltip : A string that should be displayed, when the mouse hovers over a widget.

; visible : Whether a widget is visible or not.

; resizable-widget : The widget in a group, which should be exclusively resizable.

; valid-context : A flag indicating whether the GL context for a {{glwindow}} is already initialized.

; read-only : If true, an {{edit}} or {{entry}} widget can not be changed by the user.

; align : The alignment of the widget label. May be combination of the following symbols:

* center
* top
* bottom
* left
* right
* inside
* text-over-image
* image-over-text
* clip
* wrap

; when : An indicator when a widgets callback should be invoked. The default behaviour depends on the type of the widget. Possible settings are:

* never - never invoked the callback
* changed - when the widget's value changes
* released - when the button or key is released and the value changes
* enter - when the enter key is pressed and the value changes
* always - modifier for {{released}} or {{enter}}, that indicates the callback should be invoked, even if the value doesn't change

The default behaviour is to invoke the callback whenever the value of
a widget changes, when a {{window}} is closed, when {{glwindow}} needs
to be redrawn, or a {{button}} or {{list}} item has been clicked.

; handler : The callback procedure that is invoked when the event occurs. The event is passed in a
first (and only) argument to the handler. A event is one of the symbols:

* no-event
* push
* release
* enter
* leave
* drag
* focus
* unfocus
* keydown
* keyup
* close
* move
* shortcut
* deactivate
* activate
* hide
* show
* paste
* selectionclear
* mousewheel
* dnd-enter
* dnd-drag
* dnd-leave
* dnd-release
* unknown

Additional information about event can be obtained with {{bb:event}} procedure.
Returning {{#f}} from handler indicates that widget is not interested in handling
this event. {{#t}} means that event was successfully handled. Any other value leads to
invoking default handler of this widget.

The {{html-view}} widget's {{handler}} is invoked when user tries to follow
the link (which URI is passed as an argument). {{Handler}} should return either the name 
of the temporary file or {{#f}} and set the {{text}} property.

; callback-reason : The reason for callback. Available only for {{tree}} widget. Valid values are:

* hilighted
* unhilighted
* selected
* unselected
* opened
* closed
* double-click
* widget-callback
* moved-node
* new-node
* nothing

; callback-node: The unique id of the node that caused callback. Available only for {{tree}} widget.