Bad Controls version 0.4                           |
(c) 2000, 2001 Kostas Michalopoulos aka Bad Sector |
---------------------------------------------------+

1. Installation
2. Using
3. Controls
 3.1. t_bad_checkbox
 3.2. t_bad_button
 3.3. t_bad_vtrackbar
4. Coming soon (i hope)

1. Installation
---------------

First of all note that if you use Bad Seal 0.52 you have to use BADCTRLS.DLX
in BSEAL52 directory, else use normal version. That is because Bad Seal 0.52
has improved color definitions and from one hand that makes better optical
result with BADCTRLS.DLX in BSEAL52 and from the other hand, Bad Seal 0.52's
definitions aren't compatible with other versions of SEAL so controls will
appear black.

a. copy BADCTRLS.DLX to your SEAL/Bad Seal directory (f.e. C:\SEAL)
b. add <badctrls.dlx> just before <iodlg.dlx> in APP.SET
c. copy BADCTRLS.H to your SEAL/Bad Seal's ./INCLUDE directory (f.e. C:\SEAL\INCLUDE)

simple, isn't it?


2. Using
--------

to use Bad Controls just add #include "badctrls.h" to your SEAL application.
For Example:

#include "allegro.h"
#include "seal.h"
#include "app.h"
#include "badctrls.h"

/* your program goes here */


You will found a demonstration program with this library called bcexampl.c. If
not, you will find it at www.badseal.org.

3. Controls
-----------

in version 0.4 there are 4 controls:
  t_bad_checkbox
  t_bad_button and
  t_bad_vtrackbar
  t_bad_tabbook

3.1. t_bad_checkbox
-------------------

t_bad_checkbox control is a check box for SEAL applications. Until the time that
these lines are written, there wasn't any similar control for SEAL. So let's
check how this control works.

(note: in badctrls.h you will find structure of t_bad_checkbox)

initialization:

t_rect r = rect_assign(give here your coords);
p_bad_checkbox my_checkbox = bad_checkbox_init(malloc(sizeof(t_bad_checkbox)), r, "check box's caption", MSG_msg, state);

where:

MSG_msg        is a valid SEAL message that occurs when user checks/unchecks 
              the checkbox.

state          is checkbox's state:

               BCB_UNCHECKED      unchecked
               BCB_CHECKED        checked
               BCB_GRAYED         grayed


Important note: in t_bad_checkbox structure is a field named "grayed". You MUST
NOT change this field because it's used internally by the event handler.

[new in 0.2: you can change checkbox's caption by using the 
change_caption(l_text c); function]


3.2. t_bad_button
-------------------
(new control in 0.2)

t_bad_button control is a replacement of the classic t_button control
of SEAL. This control can have more than one styles including Windows
95, Windows 3.1 and KDE styles.

(note: in badctrls.h you will find structure of t_bad_button)

initialization:

t_rect r = rect_assign(give here your coords);
p_bad_button my_button = bad_button_init(malloc(sizeof(t_bad_button)), r, "My Button", l_int style, MSG_msg);

where:

style          is button's style:

               BBS_SEAL        classic SEAL style
               BBS_BADSEAL     Bad Seal's style
               BBS_KDE         KDE-like style (not in Win95 look)
               BBS_WIN95       Windows 95 style
               BBS_WIN31       Windows 3.0 and 3.1x style
               BBS_MODERN      A more "modern" style :-)
               BBS_LIQUID      A MacOS-X button for small sizes (new in 0.3)

MSG_msg        is a valid SEAL message that occurs when user clicks on
              the button.


Important note: in t_bad_button structure is a field named "pressed". You MUST
NOT change this field because it's used internally by the event handler.

also there is an option-field named "switch-button". This makes button to act like
a checkbox but IS NOT TESTET YET so maybe there are bugs flying around.


3.3. t_bad_vtrackbar
-------------------
(new control in 0.3)


t_bad_vtrackbar is a vertical trackbar for applications like sound mixers,
volume controllers, etc. Can also act as a scroll bar but returns the value
after user releases the mouse button.

(note: in badctrls.h you will find structure of t_bad_vtrackbar)

initialization:

t_rect r = rect_assign(give here your coords);
p_bad_vtrackbar my_trackbar = bad_vtrackbar_init(malloc(sizeof(t_bad_vtrackbar)), r, MSG_msg);
my_trackbar->max = maximum_value;

where:

MSG_msg        is a valid SEAL message that occurs when user releases the
              left button on trackbar. A field in trackbar named pos contain
              the position of track (my_trackbar->pos in this example).

maximum_value  is the maximum value that the trackbar can return (minimum is
              0 - note that in t_bad_vtrackbar is a field named "min". This
              not used and is reserved for future use). By default the
              bad_trackbar_init functions set the "max" field (maximum value)
              to 100.


There is a function for changing track's position and redrawing trackbar:

my_trackbar->change_pos(my_trackbar, new_position);

where:

my_trackbar    see the example...

new_position   is the new position of trackbar.


By default bad_vtrackbar_init set track's position to 0.


3.4. t_bad_tabbook
------------------
(new control in 0.4)


t_bad_tabbook is the most usefull control in Bad Controls. It's a tab
book that helps you to have overlapped places in one rectangular area in
a window. Every tab in tab book has a title and when you click that title
tab's controls will appear (and previus tab's controls will dissappear).

(note: in badctrls.h you will find structure of t_bad_tabbook)

initialization:

t_rect r = rect_assign(give here your coords);
p_bad_tabbook my_tabbook = bad_tabbook_init(malloc(sizeof(t_bad_tabbook)), r, title);

where:

title          is first tab's title. Every tab book must have at least one
              tab (else why to exist?). You can add more tabs by using the
              add_tab function (see below).

Adding more tabs:
-----------------
To add more tabs just use the add_tab function. add_tab's syntax is:

  tabbook->add_tab(tabbook, "title for new tab");

I suppose that you can understand what second parameter is ;)

Adding controls to tabs:
------------------------
To add a control to a tab use tab[] array defined in t_bad_tabbook struct.
tab[] is an array of p_view that contains tabs's controls. So the code to
add (for example) a t_bad_button in first tab is:

  r = rect_assign(10, 80, 100, 150);
  btn = bad_button_init(malloc(sizeof(t_bad_button)), r, "Button", BBS_SEAL, MSG_xxx);
  OBJECT(tabbook->tab[0])->insert(OBJECT(tabbook->tab[0]), OBJECT(btn));

  where:
    btn                 a t_bad_button control
    tabbook             a t_bad_tabbook control

Selecting a tab:
----------------
To select a tab except by clicking it use the select_tab function like:

  tabbook->select_tab(tabbook, newtab);

where newtab is the tab that you want to select (always first is 0)

Determining when user has changed tab:
--------------------------------------
To determine when user has changed tab just make a function with this
syntax:

   void your_function(p_bad_tabbook o, l_int new_tab);

and assign on_changed field in t_bad_tabbook to this function's address:

   tabbook->on_changed = &your_function;


look bcexampl.c for an example for all controls


4. Coming soon
--------------

Controls to add soon (soon...):

t_bad_toolbar     a toolbar for SEAL applications
t_bad_radiobtn    a radio button control
t_bad_image       an image viewing control
t_bad_label       a changeable text control
t_bad_listbox     a more powerfull changeable list box

i'll see


(c) 2000, 2001 Kostas Michalopoulos aka Bad Sector

