S_WHAM, a simplified API for windowing using WHAM

Legal Obligations.

I'm not responsible for any damage/misfortune this code may do/bring to you. Use it at your own risk.

(not that I'm doing any weird things, just to be on the safe side)




Copyright Info

WHAM (including S_WHAM) is ,like Allegro, swapware. that means that if you like it, send me something in return, 'something' can be: a program you made, a postcard, some money(always useful...:), a photograph of you, your family and all your 101 dalmatians, an unknown Only Ones or Syd Barrett CD ;),... Anyway,.. ye know what I mean.

It would be nice if you mentioned me in the credits of your program, but you don't have to if you don't want to.

Please tell other people how to obtain WHAM(or spread it around).



Introduction

S_Wham is a standardized, simplified API for WHAM. Wham got quite large and I had the feeling people got scared off by the large number of settings.

S_Wham provides a standardized subset of WHAM with some standard window classes and a default 'program front end' which is somewhat W95 like.

S_Wham started as the interface for a project of mine (a povray heighfield utility, which still is nowhere near done :), and since I noticed that a lot of work on the interface came back in each program I wrote, I started making a library of it.

S_Wham is, in a way, less flexible than pure WHAM, since it hides all the internal details from the programmer, (a bit like LaTeX does for Tex, LaTeX users will know what I mean) but it takes a lot of work out of the hands of the programmer and provides an easy to use standard interface.


Using S_Wham

to use s_wham
#include <s_wham.h.h>
in your program. and call install_s_wham() (see S_Wham functions)

S_Wham functions

int install_s_wham(int card, int w, int h, int v_w, int v_h, int colordepth, char *configfile = NULL);

This function installs the S_Wham library, it also calls install_timer(), install_mouse(), install_keyboard(), set_gfx_mode() for you, so you don't need to call these anymore. just call allegro_init() and then install_s_wham( )
description of the parameters:
int card - a card constant for set_gfx_mode
int w,h - graphics mode
int v_w, v_h - virtual screen dimensions, these are not related to the virtual screen size of the graphics card, but emulated by shifting the windows around, so you can choose these as big as you like.
int colordepth - graphics mode
char *configfile - filename of a configfile, you can ignore this paramater (or set it to NULL) s_wham will then use the default config source, or you coukd call set_config_file( ) yourself.
returnvalue:
it could return -1 on error, but at the moment it just aborst the program on error, if anyone has a problem with that, mail me and I'll fix it.


void s_wham_exit();
removes s_wham, you don't need to call this, since it will be installed as an atexit function by install_s_wham.


void s_wham_restore_colors()
when you change the palette, call this to make wham redraw in the correct colours

void s_wham_redraw_desktop()
redraws the desktop

void s_wham_set_font(FONT *font);
sets the font used by S_Wham for it's menu's, window titles etc.

void s_wham_set_user_menu(MENU *m);
adds the allegro menu 'm' to the system menu of s_wham (the one you get when you click the taskbar start button)


char *s_wham_file_select(char *message, char *path, char *ext);
this is the same as the allegro file_select function but looks more 's_wham like'.
file_select docs:

Displays the Allegro file selector, with the message as caption. The path parameter contains the initial filename to display (this can be used to set the starting directory, or to provide a default filename for a save-as operation). The user selection is returned by altering path, so it should have room for at least 80 characters. The list of files is filtered according to the file extensions in ext. Passing NULL includes all files, "PCX;BMP" includes only files with .PCX or .BMP extensions. Returns zero if it was closed with the Cancel button, non-zero if it was OK'd.


Global variables

char *s_wham_about_string;
if this is not NULL, it will be printed in the 'about' box.

BITMAP *s_wham_about_bitmap;
if this is not NULL, it will be printed in the 'about' box.

int s_wham_xor_color;
the color used to draw the animated rectangles on minimising etc. by default this is makecol(255,255,255), set by install_s_wham.

FONT *_s_wham_font;
the font used by S_Wham, you should not change this directly, but only through s_wham_set_font.


S_Taskbar _s_wham_task_bar;
wanna see yer program crash?! delete this one, chrash guaranteed. but you might do tricks with is, dunno.

Background *s_wham_root_window;
the root window of s_wham, by default this is just a non-drawable solid colored object. But if you need it to be different, delete this one (delete s_wham_root_window) and create your own (s_wham_root_window = new Background) see backgrnd.h for deltails.

Classes of S_Wham

S_Wham has 2 classes, S_Window and S_Dialog, also the WHAM class Panle, can be used for message boxes etc.

S_Dialog class

The S_Dialog class is derived form the WHAM AlGuiContainer class, it contains an allegro dialog.

it's constructors are:

S_Dialog(char *title, DIALOG *dialog,int size_x,int size_y,
int pos_x = 5,int pos_y = 16);
S_Dialog(char *title, DIALOG *dialog,int size_x,int size_y,int
pos_x,int pos_y, int syspriority);





If you don't specify syspriority (using the first constructor), the window will look like a normal window.
If you specify syspriority (even if it's FALSE, using the second constructor), the window will look like a frame, it will not have a title/minimis/maximise/roll button.
If syspriority is TRUE, the window will appear on to of all ther windows, and the program use will not be able to close it, or do anything else, until the dialog finishes.
parameters:
title - the window title
dialog - an allegro dialog
size_x,size_y - the dimesnions of the window
pos_x, pos_y - position of the window, (5,5) if not specified.
syspriority - see above

AlGuiCon_functions to be used with S_Dialog.

void start(int focus_obj = -1)
starts the dialog

void stop();
stops the dialog

int get_closer_object();
get the object that stopped the dialog

int is_running();
returns TRUE if it still runs, FALSE if it has stopped.

DIALOG *change_dialog(DIALOG *new);
this replaces the dialog in the window, and returns the old one.


AlGuiCon_members to be used with S_Dialog

int delete_when_done;
when you set this to TRUE, the dialog will delete it's window when done (the Allegro DIALOG will still exist)

Pitfalls

there are some minor pitfalls in S_Dialog:

1)
the S_Dialog class puts the dialog in a window by diverting the global 'screen' pointer. If you call a function that needs the real value of 'screen' FROM WITHIN A DIALOG PROCEDURE , like most WHAM functions, you need to surround the call with
AlGuiContainer::push_gui_screen();
AlGuiContainer::pop_gui_screen();

for example if you need to update a window:


d_ladieda_proc(int msg,DIALOG *d, int c)
{
// standard dialog procedures
.
.
.
AlGuiContainer::push_gui_screen();
win->update();
AlGuiContainer::pop_gui_screen();
}


2)
change_dialog( ) is a bit dangerous to use, for you easily overlook the consequenses. as a rule of thumb, never use change_dialog when it's still running (unless you really know what you're doing)

3)
Since there is no way to intercept the messages from the allegro dialog functions AlGuiCon replaces all the dialog proc's in you dialog with its own function, which in turn calls you proc's. But even in this way it cannot intercept everything. for example, if you have a d_slide_proc, you need to use the callback function to update the S_Dialog window each time the slider moves. In the same you you'll need to rewrite dialog procs that use a scrollbar to refresh the window each time the scrollbar changes, or you won't be able to drag them with the mouse.

S_Window class

its constructors are:

S_Window(char *title, int size_x,int size_y,int pos_x = 5,int pos_y = 16);
S_Window(int size_x,int size_y,int pos_x = 5,int pos_y = 5);
S_Window(char *title,BITMAP *bmp, int pos_x = 5,int pos_y = 16);
S_Window(BITMAP *bmp,int pos_x = 5,int pos_y = 5);

these make various types of drawable windows/frames the first 2 create their own drawing surface, while the last 2 put a frame around the specified bitmap. the versions without title use a title-less frame instead of a border

Wobject_functions for use with S_Window and S_Dialog

not all Wobject functions are listed here, just the ones you are most likely to use

int show();
int hide();
void update();
void update(int x, int y, int w, int h);

these show/hide your object, update() calls show() if the object is already visible, and leaves hidden objects hidden. show()/hide() return FALSE if the object was visibility_locked. show() returns FALSE if the object was frozen. In all other cases they return TRUE.

int raise();
make this object the top object(on the screen). if there are top-locked objects, it will stay under them. returns FALSE if locked

int lower();
make this object the bottom object(on the screen). if there are bottm-locked objects, it will stay above them. returns FALSE if locked



int raise_and_lock();
raises the window, and locks it in a top position. Even if there are top-locked objects it will be raised to the top position (over the top-locked).

int move(int new_x,new_y);
moves the Wobject to a new location returns TRUE on success or FALSE if the Wobject was position-locked

int rescale(int nw_size_x, int nw_size_y);
sets the size the Wobject will be when displayed on the screen. this does not change the real size of the Wobject, only the way it looks on the screen. returns TRUE on success, FALSE if Wobject was scale-locked



void set_lock(int lock);
lock can be TRUE or FALSE this will lock the object in the drawing hierarchy. a locked object cannot be raised, so once it arrives at the bottom it stays there, (top and bottom are the dimension *into* your screen 'bottom' is 'closer' to the electron gun of your monitor, while 'top' is 'closer' to you) even if you call raise(); When the top window is locked it will stay on top and new windows will be created under it. Unless *all* windows are locked, in which case the manager can not decide if they are locked to the top or the bottom, and will open the new window on top. There is one subtle pitfall in top locked windows:
For example, you top-lock window A and then window B, next you unlock window A. Now window B will 'fall down' until it it bottom-locked. How come? The manager decides that a window is top-locked when there are only locked windows above it, so when A is above B and B is locked, it decides B is bottom-locked, and won't raise it anymore.
So when you unlock a top locked window, always call lower( ) directly afterwards. (hiding it won't help, since a hidden window is still considered to be on top). there is a special Separator class which does totally nothing ( and hence is very small) which can be used to separate you top and bottom locked objects from eachother int a case where you'd have only locked objects.



other locking functions if lock is TRUE
void set_lock_position(int lock); cannot be moved
void set_lock_size(int lock); cannot be resized (default TRUE)
void set_lock_scale(int lock); cannot be rescaled
void set_lock_viewport_position(int lock); viewport cannot be moved
void set_lock_viewport_size(int lock); viewport cannot be resized
void set_lock_visibility(int lock); object cannot be shown or hidden
void set_lock_shift(int lock) object won't respond to the shift_all function


lock can be TRUE or FALSE
all are default false, except for lock_size which is default TRUE;


Window_funcions for use with S_Dialog and S_Window

void printf();
like printf() outputs text to the window in color Window::Text_Color using the specified Window::Scroll_Behaviour (see WHAM documentation for details)

BITMAP *bmp();
returns a pointer to the user area of the window bitmap this can be drawn on, but you should not do this on S_Dialogs, for it'll look strange.

Helper_functions for use with S_Wham


void trace(char *format,...);
for debugging purposes takes printf style arguments. prints them on the screen and waits for a keypress

void ttrace(char *format,...);
like trace( ), but waits just 1 second instead of waiting for a keypress ( handy if keypresses mess up your program)

FILE *DEBUG_OUTPUT_FILE;
if this is not NULL, trace will print to this file instead of the screen;

void fatal(char *format,...);
takes a printf style message shuts down the program and prints the message to stderr

void out_of_mem(char *message);
prints the message and exits, but does not use any extra memory nor tries to remove wham from memory ( because that also costs some extra memory, which can cause the program to hang the computer) and thus leaves garbage in the memory with DPMI-servers that don't clean up on exit (such as PMODE).




And...

You can use most WHAM functions not listed here safely with S_WHAM though other classes than S_Window and S_Dialog will not interact with the taskbar.

But all functions in helper.h and winsys.h should work.

Addresses

   email:
      m.versteegh cpedu.rug.nl (while I'm still studying)

      vsteegh dds.nl   (parents,if the other on doesn't work)

   telephone:

      none

   mail:
      Martijn Versteegh

      postbox 1443

      9701 BK

      Groningen

      The Netherlands

   living:
      somewhere on the Dutch waterways on the

      motorship 'Aaltje'.

Thanks


   DJ Delorie - for DJGPP

   Shawn Hargreaves - for Allegro

   FB - for teaching me C/C++

   H.D.Zelle - for playing with the computer when we ought
   to write reports.

   All people from the Allegro mailing list that tested this lib.



   



                  that's all folks

Index