===== 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.