chickadee » bb » bb:property

bb:property WIDGET PROPERTYprocedure
(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.