boolsoft presents

Advanced Dialogs
- v1.01 -

Advanced Dialogs is cross-platform (AMS and PedroM) static library for TIGCC for creating grayscale dialogs. It combines the usefulness of AMS Dialogs with the speed of TIGCC and ExtGraph, offering all standard functions (Title, Buttons, Input, DropDown, MessgaeBox etc.) and additional useful features not offered by AMS (Multiple Tabs in a dialog, Bitmaps, CheckBoxes, ProgressBars etc.). Providing this features, Advanced Dialogs allows the easy creating of a fast and beautiful GUI for your TIGCC project.

Contents

I. II. III. IV. V. VI. VII. VIII. IX.   a)   b) X.   a)   b)   c)   d) XI. XII. XIII. XIV.

Screenshots How to include Advanced Dialogs in your TIGCC project Compability Navigation How to setup a standard dialog How to check the results of a dialog Bimaps ProgressBar and MessageBox Important notes   Interrupt handler   Misc. notes Description of the functions   Dialog functions   Bitmap functions   MessageBox functions   ProgressBar functions Credits License Contact History

I. Screenshots

		This screenshot is take from the example "Simple Dialog". It shows a dialog without tabs.
		This screenshot is take from the example "Input". It shows a dialog with an InputBox and Text. If you press [ENTER], a MessageBox is shown that displays the name that has been entered.
		This screenshot is take from the example "ProgressBar". It simply demonstrates the ProgressBar-feature.
		This screenshot is take from example "Multiple Tabs". It shows a dialog with 4 tabs. The tabs include different elements: Text, InputBoxes, CheckBoxes and a DropDown menu.
		This screenshot is take from example "Bitmap". It shows a simple dialog with a bitmap and Text with the attribute TXT_ALIGNLEFT (the first two lines).

II. How to include Advanced Dialogs in your TIGCC project


If you want to use Advanced Dialogs in your TIGCC project, you will need four files in order to get it working:

AdvDialogs.h AdvDialogs.a extgraph.h extgraph.a

Advanced Dialogs header file Advanced Dialogs archive file (the library) ExtGraph header file ExtGraph archive file

All these files can be found in the lib-directory of this package. Please note that the ExtGraph library and its functions were written by member of the TI-Chess Team (http://tict.ticalc.org) and without it, Advanced Dialogs would be useless.
If you are already using ExtGraph in your project, you do not nedd to include them once more. Just make sure that your version is not older than 2.00beta4.

To add this files to your project, put them in your source folder, and select "Project->Add Files..." from the TIGCC IDE.
Last but not least, you have to add

    #include "AdvDialogs.h"   // Powered by Advanced Dialogs v1.01 

to the files that will call functions from the Advanced Dialogs library.

III. Compability


For checking if Advanced Dialogs is compatible to your project and/or calculator, use the following table.

HW 1 HW 2 HW 3 PedroM

AMS >= 1.01 AMS >= 1.01 AMS >= 1.01 version >= 0.81

If you find any compability issues that are not listed here, please contact me!

IV. Navigation


The following table shows the keys and their meanings.

[ENTER] [ESC] [APPS] [LEFT]/[RIGHT] [UP]/[DOWN]

Closes the dialog and returns TRUE Closes the dialog and returns FALSE Switches between the tabs from left to right (Un)check CheckBoxes; Select an item in a DropDown element Switches between interactive elements (CheckBox, InputBox and DropDown)

V. How to setup a standard dialog


Before you use the Advanced Dialogs library, you should understand the structure of the dialogs you can create with it. Look at the following picture to get an idea of it.


As you can see, a dialog can contain multiple tabs, while the maximal number is 6. Each tab can contain multiple elements (e.g Text or CheckBoxes), while ýou can store up to 6 elements per tab. This makes a total of 36 (!) elements per dialog.


If you understand this structure, it is easy to set up complex dialogs. All you have to do is keep track of the correct order:

1. 2. 3.

Create a new dialog using AdvDlgNew(...) Add a tab to the dialog using AdvDlgAddTab(...) Add some elements to the tab

To make this more clear, look at the following program that will set up a dialog with two tabs. Each tab contains a line of text.

#include <tigcclib.h> #include "AdvDlgs.h"   // Powered by Advanced Dialogs v1.01 void _main (void) {   /* Turn on grayscale graphics */   if (!GrayOn()) {     return;   }   /* Use the type ADVDIALOG to create a dialog */   ADVDIALOG *dialog = AdvDlgNew(120, 40, "Dialog Test", TRUE);   /* Safety first!! */   if (dialog == NULL) {     GrayOff();     return;   }   /* Add the first tab (it is numbered with '0') */   AdvDlgAddTab(dialog, 0, "Tab No.1");     /* Add a line of text to tab '0' in line '1' */     AdvDlgAddText(dialog, 0, 1, "This is the first tab", TXT_STANDARD, COLOR_BLACK);   /* Add the second tab (numbered as '1') */   AdvDlgAddTab(dialog, 1, "Tab No.2");     /* Add a line of text to tab '1' in line '2' */     AdvDlgAddText(dialog, 1, 2, "Centered text...", TXT_CENTERED, COLOR_WHITE);   /* Buttons can be added any time to a dialog */   AdvDlgAddButton(dialog, 0, B_OK);   AdvDlgAddButton(dialog, 1, B_ESC);   /* Now, execute the dialog */   AdvDlgDo(dialog, DUMMY_HANDLER);   /* Don't forget to free the dialog after execution! */   AdvDlgFree(dialog);   /* Turn off grayscale graphics */   GrayOff(); }

Easy, isn't it?

VI. How to check the results of a dialog


If your dialog uses interactive elements (InputBoxes, CheckBoxes or DropDowns), you might want to know the values the user selected or entered.

In InputBoxes, the pointer to the inputbuffer contains the string the user entered.
When using DropDowns, the pointer to the selected argument will contain the selected argument after execution of the dialog.
CheckBoxes are different: you can check their results via a global array named AD_CHECKED. So,´you could check the content of CheckBox '2' in Tab '0' with:

    if (AD_CHECKED[0][2])

VII. Bitmaps


Starting from version 1.0, you are able to add images to dialogs (tabs), which are called bitmaps. They have their own type named ADVBITMAP. The format of bitmaps is based on the TIOS BITMAP format: A variable of type ADVBITMAP contains the x- and the y-postion of the bitmap as well as two variables of type BITMAP - one for the light and one for the dark plane. The bitmaps are drawn using the TIOS- and PedroM-built-in routine BitmapPut.

The x- and y-position of a bitmap are relative to the dialog to which it has been added (that's why they are specified when you add the bitmap, not when you create it). The bitmap is clipped inside the dialog to which it has been added.

In this version, it is only possible to add 1 bitmap to a dialog (tab), although future version might enable more bitmaps per dialog (tab).

VIII. ProgressBar and MessageBox


Beside the standard dialog functions, Advanced Dialogs also offers two other functions that are totally independent from the dialogs. These functions are AdvDlgProgressBar, which will draw a ProgressBar to add some animation to a process, and AdvDlgMessageBox, that can be used to display one-line messages with a single call.
I will explain these functions briefly, but please take a look at the examples to see some code that will make them work. See also the description of the functions for neccessary arguments for the functions.


a) ProgressBar

Look at the following table to see which routines you have to call to set up a ProgressBar:

1. 2.

Set up the ProgressBar with AdvDlgProgressBar(...) Call AdvDlgProgressUp() until the ProgressBar is filled

Please note that the ProgressBar does not save the LCD contents, so you will have to do this yourself.


b) MessageBox

To show a small MessageBox, you have simply have to call AdvDlgMessage(...) and you will get a small dialog with a title, a button and one line of text. If the user presses a key, the MessageBox will return.
MessageBox saves the LCD contents and restores the before it returns.

IX. Important notes


a) Interrupt handlers

In most grayscale programs, AUTO_INT_1 and AUTO_INT_5 are disabled to avoid the display of the 2ND, ALPHA, or diamond-indicators in the status line. Programs that are using low-level keyboard reading should disable these interrupts as well.

However, Advanced Dialogs doesn't disable interrupts to make functions like InputBox possible and to keep compability to PerdroM, which doesn't support _rowread.

Therefore, the functions AdvDlgDo(...) and AdvDlgMessageBox(...) take an interrupt handler as an argument. If your program disables interrupts, you should use the saved AUTO_INT_1 for this argument. If you do so, Advanced Dialogs will use GraySetInt1Handler(...) to reinstall a temporary AUTO_INT_1 and install DUMMY_HANDLER before it exits.

If you do not disable interrupts in your program, you should pass DUMMY_HANDLER as an argument.


b) Misc. notes

Another thing that is important when working with Advanced Dialogs is to keep track of the functions you call, because this library won't do error checking of the arguments or of the functions.
To make sure your program runs as well as it should, you must not exceed the limits of a dialog (add more than 6 tabs per dialog or more than 6 elements per tab).

If you don't want to use tabs in your dialog or if you just have one tab, all you have to do is not to call AdvDlgAddTab(...) and add all elements to tab '0'.

Advanced Dialogs is released under the GNU General Public License, so you will find the complete source in the folder "\source". If you have some experience with C, it should be easy to modify the dialog routines to fit your needs. You are completely free to add your own extensions, or to program a different style etc. Please feel free to send me your modifications - perhaps I will include them in this package.

X. Description of the functions


a) Dialog functions

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

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

width height title savescreen

short short const char * BOOL

Width of the dialog Height of the dialog Title of the dialog If you set this to TRUE, the screen will be saved and restored before and after the calling of AdvDlgDo(...).

AdvDlgNew(...) returns a pointer to the dialog that was created. If the creation fails, NULL will be returned.
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.

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

This function adds a new tab to a dialog.

dialog tab title

ADVDIALOG * short const char *

Pointer to the dialog created with AdvDlgNew(...) Number of the new tab Title of the new tab

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

This function adds a line of text to a dialog.

dialog tab line text attr color

ADVDIALOG * short short const char * short short

Pointer to the dialog created with AdvDlgNew(...) Number of the tab where the Text will appear Number of the line of the tab where the Text will appear Text to be displayed Attribute of the Text. This can either be TXT_STANDARD, TXT_ALIGNRIGHT or TXT_CENTERED Color of the text. This can either be COLOR_BLACK or COLOR_WHITE

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

This function adds an InputBox to a dialog.

dialog tab line text buffer maxsize mode color

ADVDIALOG * short short const char * char * short short short

Pointer to the dialog created with AdvDlgNew(...) Number of the tab where the InputBox will appear Number of the line of the tab where the InputBox will appear Text to be displayed (can be used for a question etc.) Buffer to store the input Maximal number of chars than can be entered If you pass INPUT_STR, letters and numbers can be entered If you pass INPUT_INT, only numbers can be entered Color of the text. This can either be COLOR_BLACK or COLOR_WHITE

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

This function adds a CheckBox to a dialog.

dialog tab line text checked color

ADVDIALOG * short short const char * BOOL short

Pointer to the dialog created with AdvDlgNew(...) Number of the tab where the CheckBox will appear Number of the line of the tab where the CheckBox will appear Text to be displayed (can be used for a question etc.) Indicates if the CheckBox will be marked Color of the text. This can either be COLOR_BLACK or COLOR_WHITE

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

This function adds a DropDown menu to a dialog.

dialog tab line text itemlist numitems selected color

ADVDIALOG * short short const char * const char ** short short * short

Pointer to the dialog created with AdvDlgNew(...) Number of the tab where the DropDown menu will appear Number of the line of the tab where the DropDown menu will appear Text to be displayed (can be used for a question etc.) Items for the DropDown menu Number of items for the DropDown menu Indicates which item will be selected by default Color of the text. This can either be COLOR_BLACK or COLOR_WHITE

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

This function 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.

dialog tab x y bitmap

ADVDIALOG * short short short ADVBITMAP *

Pointer to the dialog created with AdvDlgNew(...) Number of the tab where the DropDown menu will appear X-Position of the bitmap (relative to the dialog) Y-Position of the bitmap (relative to the dialog) Pointer to the bitmap created with AdvDlgBitmapNew(...)

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

This function adds a Button to a dialog.

dialog pos button

ADVDIALOG * short short

Pointer to the dialog created with AdvDlgNew(...) Position of the Button (0 = left, 1 = right) Type of the Button. Valid types are B_OK, B_ESC, B_YES, B_NO and B_NONE (However, it is not necessary to use B_NONE. Simply do not call this function if you don't want to add a button).

BOOL AdvDlgDo(ADVDIALOG *dialog, INT_HANDLER tempint1)

This functions executes a dialog.

dialog tempint1

ADVDIALOG * INT_HANDLER

Pointer to the dialog created with AdvDlgNew(...) AUTO_INT_1 (see Important notes for more info)

AdvDlgDo(...) returns TRUE if the user has closed the dialog by pressing [ENTER]. If the user has pressed [ESC], it will return FALSE.

void AdvDlgFree(ADVDIALOG *dialog)

This functions frees the memory used by a dialog.

dialog

ADVDIALOG *

Pointer to the dialog created with AdvDlgNew(...)

AdvDlgFree(...) simply frees the pointer using free(...). You can also use free(...), but I think doing it with AdvDlgFree(...) makes the code a bit more clear because it fits the naming convention of the other functions included in Advanced Dialogs.




b) Bitmap functions

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

This function allocates space for a bitmap and sets up the main arguments:

width height lpdata dpdata

short short unsigned char * unsigned char *

Width of the bitmap Height of the bitmap Image data for the light plane Image data for the dark plane

AdvDlgBitmapNew(...) returns a pointer to the bitmap that was created. If the creation fails, NULL will be returned.
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.
NOTE: The bitmap will be freed automatically if you call AdvDlgFree(...).




c) MessageBox functions

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

This function displays a MessageBox and waits for keypress.

title msg textcolor button tempint1

const char * const char * short short INT_HANDLER

Title of the MessageBox Text to be displayed Color of the text. This can either be COLOR_BLACK or COLOR_WHITE Button at the lower right corner. See AdvDlgAddButton(...) for a description of valid buttons. AUTO_INT_1 (see Important notes for more info)

d) ProgressBar functions

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

This function sets up a ProgressBar.

title msg steps

const char * const char * short

Title of the ProgressBar dialog Text to be displayed Number of steps of the ProgressBar

void AdvDlgProgressUp(void)

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.

XI. Credits


Advanced Dialogs
v1.01 - 22.02.2006

written by
Jonas Gehring (aka saubue),
member of boolsoft

compiled with TIGCC v0.96 Beta 6
powered by ExtGraph v2.00 (pre)beta 5
tested and debugged with TiEmu and VirtualTI

Beta-Testers:
  Epsilon
  MathStuf

Thanks to:
  The TIGCC Team for their wonderful compiler and IDE
  The TI-Chess Team for the great ExtGraph library
  The Linux Programming Group for TiEmu
  mhubi
  Epsilon and MathStuf for their suggestions (Epsilon had the great idea to use tabs)
  All people who support the community and who are trying to keep everything together

XII. License


Advanved Dialogs v1.01
Copyright (C) 2005 - 2006 Jonas Gehring

Advanved Dialogs is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

Advanved Dialogs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Advanved Dialogs; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

XIII. Contact


If you have any comments or suggestions, if you want to support boolsoft, if you have found a bug or if you just want to say "hello!", please write to:

  saubue@mobifiles.de or
  jonas.gehring@mobifiles.de

For future updates and other programs, please visit our homepage and sign out guestbook:

  http://boolsoft.mobifiles.de or
  http://boolsoft.mobifiles.com

For further discussion of Advanced Dialogs and our other projects and programs as well as for minor updates, visit our message board:

  http://boolsoft.mobifiles.de/board

If you want to meet the biggest german TI community, please visit MobiFiles:

  http://www.mobifiles.de and its message board at
  http://forum.mobifiles.de

XIV. History

Date	Version #	Features / Changes
22.02.2006	1.01	Fixed silly logical bug - right-aligned text has the attribute TXT_ALIGNRIGHT and NOT TXT_ALIGNLEFT, of course...
17.01.2006	1.0	Added Bitmap-functions Modified x- and y-Position of Elements in dialogs with no tabs Added TXT_ALIGNLEFT as a text attribute. Renamed examples and added another one to demonstrate the new Bitmap-functions
19.12.2005	1.0beta	Massive Changes in this near-final version:  - The construction of the dialogs has changed once again to make multiple tabs possible. They are called like TI-BASIC-Dialogs now.  - You are able to use tabs now, so up to 36 lines of text, input etc. can be stored into 1 dialog. You can switch tabs by pressing [APPS]  - Inputs can now scroll, so the string is not limited to the size of the InputBox  - Added DropDown menu  - Dialogs now have their own type (ADVDIALOG). They are initialized as pointers, AdvDlgNew(...) allocates the space for them.  - Added example #4 to demonstrate the new tab features  - The whole documentation has been rewritten
07.09.2005	0.91	Fixed bug in AdvDlgProgressUp() when using a 240x128 screen '\' is now also allowed in InputBoxes with INPUT_STR
29.08.2005	0.9	Finally a nearly complete version (that's the reason for 0.9) and a lot of new things:  - Dialogs have to be called totally different. This makes working with them easier and more dynamically.  - Added CheckBox-feature   - Improved ProgressBar-feature   - You can scroll through the interactive elements with [UP] and [DOWN]   - added optimizations by MathStuf that made screen centering wasting less bytes.
26.08.2005	0.5	The standard dialog is variable-sized and centered on the screen.
22.08.2005	0.46	Bugfixes and optimizations. Thanks to MathStuf!!
09.08.2005	0.45	All dialogs and the ProgressBar are now centered on a TI92+/V200, too
08.08.2005	0.4	Added MessageBox-function
06.08.2005	0.3	Added ProgressBar-functions Added example #3
12.06.2005	0.22	Fixed bug in example #2 Documentation updated
20.03.2005	0.21	First release