Advanced Dialogs

1.0.7

Advanced Dialogs is a 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 these features, Advanced Dialogs allows the easy creating of a fast and beautiful GUI for your TIGCC project.

For a complete function overview, please see AdvDialogs.h

If you are new to Advanced Dialogs, you should read this document for a short introduction.

Table of Contents:

  1. Screenshots
  2. Howto include Advanced Dialogs in your TIGCC project
  3. Compability
  4. Navigation
  5. Howto setup a standard dialog
  6. Howto check the results of a dialog
  7. Bitmaps
  8. ProgressBar and MessageBox
  9. Important notes
    1. Interrupt handlers
    2. Misc. notes
  10. Credits
  11. License
  12. Contact
  13. History

1. Screenshots:

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

2. Howto include Advanced Dialogs in your TIGCC project

If you want to use Advanced Dialogs in your TIGCC project, you will need to add four files in order to get it working:
AdvDialogs.h Advanced Dialogs header file
AdvDialogs.a Advanced Dialogs archive file (the library)
extgraph.h ExtGraph header file
extraph.a ExtGraph archive file

The AdvDialogs*-files can be found in the lib-directory of this package. The ExtGraph library can be downloaded at the TI-Chess Team homepage (http://tict.ticalc.org), allthough it is recommend to get a svn copy of the ExtGraph svn repository at http://opensvn.csie.org/ExtGraph. Please note that the ExtGraph library and its functions were written by members of the TI-Chess Team 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 need to add something like

        #include "AdvDialogs.h"   // Powered by Advanced Dialogs 1.0.7

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

3. Compability

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

HW 1 AMS >= 1.01
HW 2 AMS >= 1.01
HW 3 AMS >= 1.01
PedroM version >= 0.81

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

4. Navigation

The following table shows the keys and their meanings:

[ENTER] Closes the dialog and returns TRUE
[ESC] Closes the dialog and returns FALSE
[APPS] Switches between the tabs from left to right
[LEFT]/[RIGHT] (Un)check CheckBoxes; Select an item in a DropDown element
[UP]/[DOWN] Switches between interactive elements (CheckBox, InputBox and DropDown)

5. Howto 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:

structure.png

Dialog structure

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 you 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. Create a new dialog using AdvDlgNew()
  2. Add a tab to the dialog using AdvDlgAddTab()
  3. 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 1.0.7


 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(); 
                AdvDlgFree(dialog);
                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?

6. Howto 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])
        {
                // CheckBox is checked
        }
        else
        {
                // CheckBox is not checked
        }

7. 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).

See also:
_advbitmap

8. 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(), which 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.

8.1 ProgressBar

The neccessary function calls to setup a ProgressBar are

  1. Setup the ProgressBar with AdvDlgProgressBar()
  2. Cal AdvDlgProgressUp() until the ProgressBar is full
Please note that the ProgressBar does not save the LCD contents, so you will have to do this by yourself.

8.2 MessageBox

To show a small MessageBox, you simply have to call AdvDlgMessageBox() 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 close and the function returns. MessageBox saves the LCD contents and restores them before it returns.

See also:
AdvDlgProgressBar

AdvDlgMessageBox

9. Important notes

9.1 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.

9.2 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, i.e do not add more than 6 tabs per dialog, 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 Lesser 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.

10. Credits

Advanced Dialogs
version 1.0.7 - 05.11.2008

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

compiled with TIGCC v0.96 Beta 8
powered by ExtGraph
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)
    Lionel Debroux for his patches and tips
    Lachprog and Boscop for their useful bug reports
    All people who support the community and who are trying to keep everything together

11. License

Advanved Dialogs 1.0.7
Copyright (C) 2005 - 2008 Jonas Gehring

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

Advanced 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

12. 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@boolosft.org or
    jonas.gehring@boolsoft.org

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

    http://www.boolsoft.org

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

    http://board.boolsoft.org

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

13. History

DateVersion #Features / Changes

XX.08.20081.0.7 Fixed bug in message box button drawing reported by Boscop
Added missing dot in version naming scheme
02.02.20081.06 Fixed a bug reported by Lachprog and reverted DropDown selection colors

12.09.20071.05 Added patches from Lionel Debroux (thanks!)
Dialogs can now hold up to 6 bitmaps per tab
Fixed MessageBox button text color
ExtGraph is not distributed with Advanced Dialogs any more
Examples are documented now
Some small size optimizations

04.08.20071.04 Advanced Dialogs now uses the GNU Lesser General Public License (LGPL)

30.07.20071.03 Fixed multiple tabs bug reported by Lachprog

10.07.20071.02 Fixed font bug reported by Lachprog
Fixed bug in some examples (not freeing memory if GrayOn() fails)
Updated documentation, now using doxygen

22.02.20061.01 Fixed silly logical bug - right-aligned text has the attribute TXT_ALIGNRIGHT and not TXT_ALIGNLEFT, of course...

17.01.20061.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.20051.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.20050.91 Fixed bug in AdvDlgProgressUp() when using a 240x128 screen
'\' is now also allowed in InputBoxes with INPUT_STR

29.08.20050.9 Finally a nearly complete version (that's the reason for 0.9) and a lot of new stuff:
 - 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.20050.5 The standard dialog is variable-sized and centered on the screen

22.08.20050.46 Bugfixes and optimizations
Thanks to MathStuf!

09.08.20050.45 All dialogs and the ProgressBar are now centered on a TI92+/V200, too

08.08.20050.4 Added MessageBox-function

06.08.20050.3 Added ProgressBar-functions
Added example #3

12.06.20050.22 Fixed bug in example #2
Documentation updated

20.03.20050.21 First release

Generated on Wed Nov 5 09:46:56 2008 for Advanced Dialogs by  doxygen 1.5.7.1