===== bb:property

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

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.