Button Package 3.0.2

by Francois Marchal
(c) ACI SA 1991 - 1997

Thanks to Florent Pillet for some fixes and for the 'cicn' and 'IconSuit' implementation.

This external and the source code is free.

Button package is made of two externals area that can display graphical buttons.
Buttons can be displayed using PICT, cicn, icl8 or ICON resources.

%bp_Button acts as a button, and %bp_Radio Button acts as a radio button.

Command List :

----------------------------------------------------------------------------
bp_Get( ButtonReference ) -> button state

This routine should be called on the script of each button area.
It tells you if the last action on the button was a valid click.
If you don't call it, the script will be always called, even if the 
user click in the button and release the mouse outside the button,
or even if the button is disabled.

Ex :

if ( bp_Get(self>>) = 1)
  ` valid click
else
  ` not a valid click
end if


----------------------------------------------------------------------------
bp_Read( ButtonReference ) -> button state

This routine is used to know the state of a radio button area.
Value is 1 if the button is down and 0 if it's up.


----------------------------------------------------------------------------
bp_SET( Button Reference, state )

This routine sets the state of a radio button area. Possible
values are : 1 down or 0 up.

----------------------------------------------------------------------------
bp_DISABLE( Button Reference )

This routine disables the button area. The button will appears dimmed.

----------------------------------------------------------------------------
bp_ENABLE( Button Reference )

This routine enables a previously disabled button area.

----------------------------------------------------------------------------
bp_SET PICT( Button Reference, Up PICT ID, Down PICT ID, Disabled PICT ID )

This routine specify the PICT resources ID used to display the different
states of the buttons.

You should pass the ID of the PICT resources needed. You can paste theses PICT
resources in your structure file using ResEdit.

If you pass any negative value for up or down PICT, the previous value will not be modified.
If you pass -1 for the disabled PICT, the disabled button will be dimmed.
If you pass -2 for the disabled PICT, the previous value will not be modified.

----------------------------------------------------------------------------
bp_SET ICON( Button Reference, ICON ID )

This routine specify the icon family resource ID used to display the different
states of the button.

An icon family is a set of 'icl8', 'icl4' and 'ICON' resources. You can create
and edit them in your structure file using ResEdit.

----------------------------------------------------------------------------
bp_SET ICON( Button Reference, up cicn ID, down cicn ID, disabled cicn ID )

This routine specify the 'cicn' resources ID used to display the different
states of the buttons.

You should pass the ID of the 'cicn' resources needed. You can create and 
edit theses resources in your structure file using ResEdit.

If you pass any negative value for up or down cicn, the previous value will not be modified.
If you pass -1 for the disabled cicn, the disabled button will be dimmed.
If you pass -2 for the disabled cicn, the previous value will not be modified.

----------------------------------------------------------------------------
bp_SET TITLE( Button Reference, Title, Font number, Size, Style )

This command sets the title and style for the button.

----------------------------------------------------------------------------
bp_SET OFFSET( Button Reference, X up offset, Y up offset, down X offset, down Y offset )

This commands specifies the horizontal and vertical offsets to apply to the title position
when button is up or down.
You can adjust these values to fit your button design.

----------------------------------------------------------------------------
bp_SET SCALE( Button Reference, methode )

if methode is 1, the PICT is drawn at its original scale. If methode is 2,
the PICT is stretched to fit the area rectangle.

----------------------------------------------------------------------------
bp_SET SOUND( Button Reference, up sound, down sound )

This command specifies the sounds to play when the button is pushed, and
the sound to play when the button is released. This commands works only
on a Macintosh. Sounds can be stored as 'snd ' resources in the 4D structure file
or be stored in the system.

----------------------------------------------------------------------------
bp_SET COLOR( Button Reference, color index )

This commands sets the color of the title of the button.
Color is an index in 4D palette.

----------------------------------------------------------------------------
bp_SET BAKCOL( Button Reference, color index )

This commands sets the color of the background of the button.
Color is an index in 4D palette.

----------------------------------------------------------------------------
bp_Get state( Button Reference ) -> Button state

This function returns 1 if the button is enabled, and 0 if the button
was disabled.

----------------------------------------------------------------------------
bp_SET CURSOR( Button Reference, cursor up, cursor down, cursor disabled )

This function specifies the cursors resources ID to use.
Cursors are stored in the structure resource file as 'crsr' color cursors
or 'CURS' black and white cursors.

On Windows, only black and white 'CURS' resources are supported.



----------------------------------------------------------------------------
------------------------ SETTING DEFAULT VALUES ----------------------------
----------------------------------------------------------------------------


----------------------------------------------------------------------------
bp_DEFLT PICT( up, down, disabled, up radio button, down radio button, disabled radio button )

This commands set the default value for the buttons and radio buttons PICT ID.

----------------------------------------------------------------------------
bp_DEFLT TITLE( chars to jump, Font number, Size, Style )

This command sets the default amount of char to jump to get the title of
the button from the area name, and the default font and style.

Ex : 
If you specify 2 chars to jump, the title of a button named "b_OK" will be "OK"

----------------------------------------------------------------------------
bp_DEFLT OFFSET( X up offset, Y up offset, down X offset, down Y offset )

This commands specifies the default horizontal and vertical offsets to apply to 
the title position when button is up or down.

----------------------------------------------------------------------------
bp_DEFLT SCALE( methode )

This command specifies the default methode to display the buttons pictures.
if methode is 1, the PICT is drawn at its original scale. If methode is 2,
the PICT is stretched to fit the area rectangle.

----------------------------------------------------------------------------
bp_DEFLT SOUND( up sound, down sound )

This command specifies the default sounds to play when the button is pushed, and
the sound to play when the button is released.
Sounds are implemented only on Macintosh.
Sounds can be stored as 'snd ' resources in the 4D structure file or be stored
in the system.

----------------------------------------------------------------------------
bp_DEFLT COLOR( color index )

This commands sets the default color of the titles of the buttons.
Color is an index in 4D palette.

----------------------------------------------------------------------------
bp_DEFLT BAKCOL( color index )

This commands sets the default color of the backgrounds of the buttons.
Color is an index in 4D palette.

----------------------------------------------------------------------------
bp_DEFLT CURSOR( cursor up, cursor down, cursor disabled )

This function specifies the default cursors resources ID to use.
Cursors are stored in the structure resource file as 'crsr' color cursors
or 'CURS' black and white cursors.

On Windows, only black and white 'CURS' resources are supported.