AdvDialogs.h File Reference

This file bundles all functions offered by Advanced Dialogs. More...

Go to the source code of this file.

Data Structures
struct	ADVEL
	Structure for a dialog element. More...
struct	ADVBITMAP
	Structure for a bitmap. More...
struct	ADVTAB
	Structure for a dialog tab. More...
struct	ADVDIALOG
	Structure for a dialog. More...
Defines
#define	GRAYPLANES   GrayGetPlane(DARK_PLANE), GrayGetPlane(LIGHT_PLANE)
	Just a short macro to make working with grayscales easier.
#define	ADVDLG_VERSION_STR   "1.0.7"
	The Version number as a string.
Typedefs
typedef unsigned char	uchar
	Convenience type for unsigned char.
Enumerations
enum	_inputModes { INPUT_STR, INPUT_INT }
	Describes valid input modes for InputBoxes. More...
enum	_textAttributes { TXT_STANDARD, TXT_ALIGNRIGHT, TXT_CENTERED }
	Describes vaild text attributes. More...
enum	_buttonTypes { B_NONE = 0, B_OK, B_ESC, B_YES, B_NO }
	Describes valid buttons for an advanced dialog. More...
Functions
ADVDIALOG *	AdvDlgNew (short width, short height, const char *title, BOOL savescreen)
	Creates and allocates space for a new dialog.
void	AdvDlgAddTab (ADVDIALOG *dialog, uchar tab, const char *title)
	Adds a Tab to a dialog.
void	AdvDlgAddText (ADVDIALOG *dialog, uchar tab, uchar line, const char *text, uchar attr, uchar color)
	Adds a Text element to a dialog.
void	AdvDlgAddInputBox (ADVDIALOG *dialog, uchar tab, uchar line, const char *text, char *buffer, short maxsize, uchar mode, uchar color)
	Adds an InputBox element to a dialog.
void	AdvDlgAddCheckBox (ADVDIALOG *dialog, uchar tab, uchar line, const char *text, BOOL checked, uchar color)
	Adds a CheckBox element to a dialog.
void	AdvDlgAddDropDown (ADVDIALOG *dialog, uchar tab, uchar line, const char *text, const char **itemlist, short numitems, short *selected, uchar color)
	Adds a DropDown menu to a dialog.
void	AdvDlgAddButton (ADVDIALOG *dialog, uchar pos, uchar button)
	Adds a button to a dialog.
char	AdvDlgAddBitmap (ADVDIALOG *dialog, uchar tab, short x, short y, ADVBITMAP *bitmap)
	Adds a Bitmap to a dialog.
ADVBITMAP *	AdvDlgBitmapNew (short width, short height, const unsigned char *lpdata, const unsigned char *dpdata)
	Creates a new Bitmap.
BOOL	AdvDlgDo (ADVDIALOG *dialog, INT_HANDLER tempint1)
	Executes a Dialog.
void	AdvDlgFree (ADVDIALOG *dialog)
	Frees them memory used by a dialog.
short	AdvDlgMessageBox (const char *title, const char *msg, uchar textcolor, uchar button, INT_HANDLER tempint1)
	Shows a MessageBox.
void	AdvDlgProgressBar (const char *title, const char *msg, short steps)
	Initializes a progress bar.
void	AdvDlgProgressUp (void)
	Updates the progress bar.
void	SaveScreen (void)
	Saves grayscale screen contents.
void	GrayDrawColorString (short x, short y, const char *str, uchar color, uchar mode)
	Draws a colored string (black or white).
void	RestoreScreen (void)
	Restores grayscale screen contents.
void	ClearKbdQueue (void)
	Clears the keyboard queue.
void	GetKey (void *kbq, short *key)
	Waits for a keypress and stores it in key.
Variables
BOOL	AD_CHECKED [6][6]
	CheckBox indicators.

---

Detailed Description

This file bundles all functions offered by Advanced Dialogs.

This is the only file you will need when working with Advanced Dialogs, since it has got prototypes of all the function offered by this library and data structure definitions for the types that are used.

Definition in file AdvDialogs.h.

---

Enumeration Type Documentation

enum _inputModes

Describes valid input modes for InputBoxes.

Enumerator:

INPUT_STR	All alphanumeric characters are allowed.
INPUT_INT	Only numbers (0-9) are allowed.

Definition at line 63 of file AdvDialogs.h.

enum _textAttributes

Describes vaild text attributes.

Enumerator:

TXT_STANDARD	Standard (left-aligned) text.
TXT_ALIGNRIGHT	Right-aligned text.
TXT_CENTERED	Centered text.

Definition at line 72 of file AdvDialogs.h.

enum _buttonTypes

Describes valid buttons for an advanced dialog.

Enumerator:

B_NONE	No button.
B_OK	Button with text "OK".
B_ESC	Button with text "ESC".
B_YES	Button with text "YES".
B_NO	Button with text "NO".

Definition at line 83 of file AdvDialogs.h.

---

Function Documentation

ADVDIALOG* AdvDlgNew	(	short	width,
		short	height,
		const char *	title,
		BOOL	savescreen
	)

Creates and allocates space for a new dialog.

This function allocates space for a dialog and sets up a few main arguments.

Note:

You should always check the result of AdvDlgNew() to make sure that there is enough memory available. If the function returns NULL you should not proceed with building the dialog.

Parameters:

	width	The width of the dialog
	height	The height of the dialog
	title	The title of the dialog
	savescreen	TRUE if the screen should be restored after executing the dialog, FALSE otherwise

Returns:

A pointer to the dialog that was created. If the creation fails NULL will be returned.

Examples:

adbmp.c, adinput.c, admtabs.c, and adsmpl.c.

Definition at line 61 of file Dialog.c.

void AdvDlgAddTab	(	ADVDIALOG *	dialog,
		uchar	tab,
		const char *	title
	)

Adds a Tab to a dialog.

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew
	tab	The number of the new tab
	title	The title of the new tab

Examples:

admtabs.c.

Definition at line 118 of file Dialog.c.

void AdvDlgAddText	(	ADVDIALOG *	dialog,
		uchar	tab,
		uchar	line,
		const char *	text,
		uchar	attr,
		uchar	color
	)

Adds a Text element to a dialog.

See also:

_textAttributes

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tab	The tab to which the Text should be added
	line	The line in a tab where the Text should be added
	text	The text to be displayed
	attr	Text attribute
	color	Color of the text. This can be either COLOR_BLACK or COLOR_WHITE

Examples:

adbmp.c, adinput.c, admtabs.c, and adsmpl.c.

Definition at line 134 of file Dialog.c.

void AdvDlgAddInputBox	(	ADVDIALOG *	dialog,
		uchar	tab,
		uchar	line,
		const char *	text,
		char *	buffer,
		short	maxsize,
		uchar	mode,
		uchar	color
	)

Adds an InputBox element to a dialog.

See also:

_inputModes

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tab	The tab to which the InputBox should be added
	line	The line in a tab where the InputBox should be added
	text	Text to be display on the left side of the input field
	buffer	Buffer to store the input from the user
	maxsize	Maximal number of characters that can be entered
	mode	Input mode of the InputBox
	color	Color of the text. This can be either COLOR_BLACK or COLOR_WHITE

Examples:

adinput.c, and admtabs.c.

Definition at line 145 of file Dialog.c.

void AdvDlgAddCheckBox	(	ADVDIALOG *	dialog,
		uchar	tab,
		uchar	line,
		const char *	text,
		BOOL	checked,
		uchar	color
	)

Adds a CheckBox element to a dialog.

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tab	The tab to which the CheckBox should be added
	line	The line in a tab where the CheckBox should be added
	text	Text to be display on the left side of the CheckBox
	checked	Initial state of the checkbox (TRUE means checked, FALSE means unchecked)
	color	Color of the text. This can be either COLOR_BLACK or COLOR_WHITE

Examples:

admtabs.c.

Definition at line 158 of file Dialog.c.

void AdvDlgAddDropDown	(	ADVDIALOG *	dialog,
		uchar	tab,
		uchar	line,
		const char *	text,
		const char **	itemlist,
		short	numitems,
		short *	selected,
		uchar	color
	)

Adds a DropDown menu to a dialog.

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tab	The tab to which the DropDown menu should be added
	line	The line in a tab where the DropDown menu should be added
	text	Text to be display on the left side of the DropDown menu
	itemlist	Pointer to an array of strings that contains the text for the items
	numitems	Number of items in itemlist
	selected	Indicates which item will be selected by default
	color	Color of the text. This can be either COLOR_BLACK or COLOR_WHITE

Examples:

admtabs.c.

Definition at line 169 of file Dialog.c.

void AdvDlgAddButton	(	ADVDIALOG *	dialog,
		uchar	pos,
		uchar	button
	)

Adds a button to a dialog.

See also:

_buttonTypes

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	pos	Position of the button (0 for left, 1 for right)
	button	Type of the button

Examples:

adbmp.c, adinput.c, admtabs.c, and adsmpl.c.

Definition at line 127 of file Dialog.c.

char AdvDlgAddBitmap	(	ADVDIALOG *	dialog,
		uchar	tab,
		short	x,
		short	y,
		ADVBITMAP *	bitmap
	)

Adds a Bitmap to a dialog.

The bitmap will be clipped inside the dialog. The positions are relative to the the dialog positions on the screen. You can add up to 6 bitmaps to a tab. If this function returns -1, there are already 6 elements in this dialog

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tab	The tab to which the Bitmap should be added
	x	X-Position of the Bitmap (relative to the Dialog)
	y	Y-Position of the Bitmap (relative to the Dialog)
	bitmap	Pointer to the Bitmap created with AdvDlgBitmapNew()

Returns:

The number of bitmaps in the selected tab, -1 if there is no more space for bitmaps in the selected tab

Examples:

adbmp.c.

Definition at line 182 of file Dialog.c.

ADVBITMAP* AdvDlgBitmapNew	(	short	width,
		short	height,
		const unsigned char *	lpdata,
		const unsigned char *	dpdata
	)

Creates a new Bitmap.

Note:

You should always check the result of AdvDlgBitmapNew() to make sure that there is enough memory available. If the function returns NULL you, should not add the bitmap to dialog.

The bitmap will be freed automatically if you call AdvDlgFree().

Returns:

A pointer to the new Bitmap, or NULL in case of an error

Examples:

adbmp.c.

Definition at line 38 of file Bitmap.c.

BOOL AdvDlgDo	(	ADVDIALOG *	dialog,
		INT_HANDLER	tempint1
	)

Executes a Dialog.

Parameters:

	dialog	Pointer to the dialog created with AdvDlgNew()
	tempint1	AUTO_INT_1 (see Important notes for more information)

Returns:

TRUE if the user closed the dialog by pressing [ENTER], FALSE if the user pressed [ESC]

Examples:

adbmp.c, adinput.c, admtabs.c, and adsmpl.c.

Definition at line 353 of file Dialog.c.

void AdvDlgFree

(

ADVDIALOG *

dialog

)

Frees them memory used by a dialog.

AdvDlgFree() simply frees the pointer using free() and checks the dialog for Bitmaps. If Bitmaps are found, they are also freed.

Parameters:

dialog

Pointer to the dialog created with AdvDlgNew()

Examples:

adbmp.c, adinput.c, admtabs.c, and adsmpl.c.

Definition at line 100 of file Dialog.c.

short AdvDlgMessageBox	(	const char *	title,
		const char *	msg,
		uchar	textcolor,
		uchar	button,
		INT_HANDLER	tempint1
	)

Shows a MessageBox.

Displays a MessageBox and waits for a keypress. The screen is being saved before showing the MessageBox and restored after the user has pressed a key.

Parameters:

	title	Title of the MessageBox
	msg	Text to be displayed
	textcolor	Color of the text. This can either be COLOR_BLACK or COLOR_WHITE
	button	Button at the lower right corner
	tempint1	AUTO_INT_1 (see Important notes for more information)

Returns:

The key pressed by the user

Examples:

adinput.c.

Definition at line 31 of file MessageBox.c.

void AdvDlgProgressBar	(	const char *	title,
		const char *	msg,
		short	steps
	)

Initializes a progress bar.

This function will initialize and draw a ProgressBar. Use AdvDlgProgressUp() to update the ProgressBar.

Parameters:

	title	Title of the ProgressBar
	msg	Text to be displayed
	steps	Number of steps of the ProgressBar

Examples:

adpbar.c.

Definition at line 56 of file ProgressBar.c.

void AdvDlgProgressUp

(

void

)

Updates the progress bar.

This functions will add another "step" to a ProgressBar that has been created with AdvDlgProgressBar(). If you call this functions steps times (you should have passed steps as an argument to AdvDlgProgressBar()), the ProgressBar will be full.
If you call this function and the ProgressBar is already full, it will do nothing.

Examples:

adpbar.c.

Definition at line 34 of file ProgressBar.c.

void SaveScreen

(

void

)

Saves grayscale screen contents.

A small utility function that saves the grayscale screen contents using Advanced Dialogs's temporary screen buffers.
Use RestoreScreen() to restore the screen contents.

Note:

This function is mainly for internal use

Definition at line 67 of file Util.c.

void GrayDrawColorString	(	short	x,
		short	y,
		const char *	str,
		uchar	color,
		uchar	mode
	)

Draws a colored string (black or white).

Note:

This function is mainly for internal use

Parameters:

	x	X-Position of the string
	y	Y-Position of the string
	str	Text to be drawn
	color	Text color (COLOR_BLACK or COLOR_WHITE)
	mode	Text mode (TXT_NORMAL or TXT_CENTERED)

Definition at line 52 of file Util.c.

void RestoreScreen

(

void

)

Restores grayscale screen contents.

A small utility function that restores the grayscale screen contents using Advanced Dialogs's temporary screen buffers.
Use SaveScreen() to save the screen contents.

Note:

This function is mainly for internal use

Definition at line 85 of file Util.c.

void ClearKbdQueue

(

void

)

Clears the keyboard queue.

Note:

This function is mainly for internal use

Examples:

adinput.c, and admtabs.c.

Definition at line 36 of file Util.c.

void GetKey	(	void *	kbq,
		short *	key
	)

Waits for a keypress and stores it in key.

Note:

This function is mainly for internal use

Definition at line 43 of file Util.c.