Properties module

This documentation is poor. If you need something, look into the source ;-)

Table of contents:

Credits
What's this?
Creating a property sheet.
Adding and Setting Properties
Events

Martin Stachoň © 2002
martin.stachon@tiscali.cz,
http://www.webpark.cz/stachon/

Thanks to Judith Evans and Roland Stowasser for testing and suggestions.

Free for non-commercial use. Contact author for use in commercial applications.

This library lets you add a Property sheet to your win32lib program. At this point, only one sheet per program is supported. Property sheet is table of two columns. The left column has name of a property and the right has its value, which is editable in various ways. Property sheet looks like this :


Features:

• Various types of properties : Button, Edit text, Edit text with button, Button, Dropdown list, Combo Box and Check box.
• Fast scrolling, resizing and updating (compared to David Cuny's properties)
• Expandable subitems.
• Flexible interface of events.

This version requires win32lib 0.55.x, 0.57.x or later, preferably 0.58 (when aviable)

Property sheet is created with function :

sheetId = createProperties(integer hParent, integer x, integer y, integer cx, integer cy, integer capCX)

hParent is a win32lib id of Property sheet parent, the control in which it will be located.
x,y,cx,cy is position and dimensions of property sheet.
capCX is width of the left column.

Returns a win32lib id to Property sheet (actually it is a Window)

After you have created a Property Sheet, you can add properties to it. Properties appear in the order you add them, also you must child properties right after its parent is added. Property which has a child is marked with '+' sign and clicking on it expands its children. There is no way to delete a property, however you can hide it. The routine used for adding is:

propId = addProperty(sequence caption, integer parent, integer pType)

caption is caption of the property in the left column.
parent is parent of this property, this allows you create hierarchical properties. For no parent (root) use 0.
pType specifies property type. Can be one of the following :


ptNone : Only caption, value is not shown nor editable.
ptEditBox : Value is editable via EditBox.
ptComboBox : Value is editable via ComboBox. User can either type value, or choose from drop-down list.
ptDropDownList : Value is editable via DropDownList. User can select a value from list.
ptButton : A clickable button with variable text.
ptCheckBox : Check box - True/False.
ptEditAndButton : Value is editable via EditBox and user can invoke an action via "..." button on right.

Returns id to that property, which is later used in other routines.

After you are done adding properties and setting their values, you should draw them by calling redrawProperties(1)

setProperty(integer id, object value)
id is property id returned by addProperty()
value is new value. For all types except CheckBox, which accepts only True/False (1/0), it is text (sequence).

setPropertyCombo(integer id, integer index, sequence list)
id is property id returned by addProperty()
index is new index (selected item from list)
list sequence of items to be in list, if it is empty sequence, it is not used.

value = getProperty(integer id)
id is property id returned by addProperty()
Returns property value. For all types except CheckBox, which has only True/False (1/0), it is text.

showProperty(integer id, integer value)
id is property id returned by addProperty()
value is the new state : True/False (1/0)

setPropEnabled(integer id, integer value)
id is property id returned by addProperty()
value is the new state : True/False (1/0)

toggleProperty(integer id)
expandProperty(integer id)
collapseProperty(integer id)
id is property id returned by addProperty()

setPropWaitForEnter(integer id, integer bool)

setPropsWaitForEnter(integer id, integer bool)
Same as setPropWaitForEnter, but sets all properties.

This library lets you set up handlers to invoke when an event happens with certain property cell. You register handler with:

setPropHandler(integer id, integer event, integer rid)
id is property id returned by addProperty()
event is event to register (see below)
rid is routine_id of function to be invoked

function my_handler (integer cell, integer event, sequence params)

Events list

peLeftUp

Description Invoked whenever an enabled property is clicked with left mouse button.
params = {}
Return value Not used

peRightUp

Description Invoked whenever an enabled property is clicked with right mouse button. Typically used to show a popup menu.
params = {mouse_x, mouse_y} -- mouse position relative to Property Sheet (useful for popup()).
Return value Not used

peDblClick

Description Invoked whenever user double clicks on enabled property with left button. Note: as for win32lib 0.57.9, this doesn't work with EditText. You need to add w32Clickable to classAttr for EditText.
params = {}
Return value Not used

peEditButton

Description Used only with property type ptEditAndButton. Invoked when the "..." button is clicked.
params = {text} -- current text of edit box
Return value Handler returns the new text for edit box.

peChange

Description Invoked whenever property value has been changed.
params = {text} -- the new value
Return value Handler returns one of the following:

1 (True) : New value is valid.
0 (False) : New value is invalid and previous value is restored in edit box.
prInvalidDontChange : New value is invalid, but keep it in edit box. Eg. when you consider "" as invalid, but you want to give user the chance to type in new value after he deleted all text, instead of popping the previous value.