This is Info file jptui.info, produced by Makeinfo version 1.68 from the
input file jptui.txi.

INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* JPTUI: (jptui).
        Jean-Pierre Delprat's Textmode User Interface library.
END-INFO-DIR-ENTRY


File: jptui.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

JPTUI
=====



 JPTUI is a visually-attractive object-oriented Textual User Interface for
DJGPP and Borland C++. Designed for C++, it provides both a simple to use
and a powerful application programming interface. This interface is
described in this document.

* Menu:

* Introduction::                                     An introduction to JPTUI
* What's new::                                            What's new in JPTUI
* Latest Version::                     How to get the latest version of JPTUI
* Files::                                            What are all these files
* Copyright::                                   Copyright and license details
* Technical Information::                               Technical information
* Contributions::                        What to do if you want to contribute
* Debug::                                                        How to debug
* Author::                                                   About the author
* FAQ::                                            Frequently Asked Questions
* Credits::                                                           Credits

* Preprocessor Symbols::                  Information on each symbol #defined
* Datatypes::                                  Explanations of each data type
* Structures::                                 Explanations of each structure
* Global Variables::         Details of each global variable defined by JPTUI
* Functions and Macros::      An explanation of each JPTUI function and macro
* Classes::                   A complete description of the classes available

* Menu:

* Concept Index::                         An index of all concepts discussed.


File: jptui.info,  Node: Introduction,  Next: Latest Version,  Prev: Top,  Up: Top

Introduction
============

 JPTUI provides many features which allow you to quickly create
professional, quality user interfaces for MS-DOS programs :


 ---------------------------------------------------------------------
|     Push buttons      |      List boxes      |       Tab bars       |
|      Check boxes      |     Combo boxes      |        Frames        |
|     Radio buttons     |  Text editing zones  |        Menus         |
|        Gauges         | String editing zones |                      |
|---------------------------------------------------------------------|
|          Message boxes          |      Multi-language support       |
|           Input boxes           |                                   |
|       File selection boxes      | Support for compressed data files |
|      Hypertext help system      |that can be linked to the .exe file|
|---------------------------------------------------------------------|
|                            And much more...                         |
 ---------------------------------------------------------------------

JPTUI can be used :

 ---------------------------------------------------------------------
| Full screen                : special font, graphical mouse pointer  |
| In a DOS box under Windows : standard font, Windows mouse pointer   |
 ---------------------------------------------------------------------

- IMPORTANT ------------------------------------------------------------

Don't forget to read the technical information (*note Technical Information::.) to avoid compiling
problems.


File: jptui.info,  Node: Latest Version,  Next: Copyright,  Prev: Introduction,  Up: Top

Latest Version
==============

 JPTUI is available on :


+ My web page www.teaser.fr/~jpdelprat

  You can always download the latest version of JPTUI from this page.

+ Simtel.net sites (www.simtel.net/simtel.net or any mirror)

  You can download the latest version of JPTUI (except beta versions)
  from these sites. The libraries are located in the following
  directories :
  > Borland version : pub/simtelnet/msdos/cpluspls
  > DJGPP version   : pub/simtelnet/gnu/djgpp/v2tk

+ x2ftp programming archives (x2ftp.oulu.fi or any mirror)

  You can download JPTUI from these sites, but it always takes a long
  time before it arrives there.


File: jptui.info,  Node: Copyright,  Next: Contributions,  Prev: Latest Version,  Up: Top

Copyright
=========

 You are free to copy and distribute JPTUI under the condition that all of
the files are included in their original and unmodified state.

 You may use JPTUI in your own programs without having to pay any form of
license fees or royalties.

 However, a post-card or some chocolates or anything else would be very
appreciated (email me (*note Author::.) to have my post address).

 If you have written an application with JPTUI, please send me a demo or at
least some screen shots, so that I can add some examples on my home page.
Thanks by advance.


File: jptui.info,  Node: Contributions,  Next: Author,  Prev: Copyright,  Up: Top

Contributions
=============

 If you have any code to contribute to JPTUI, please send it directly to the
author (*note Author::.) - me :) -, as opposed to releasing your contribution
separately. This ensures that all of the contributions will work together,
and maintain compatibility with future versions of JPTUI.


File: jptui.info,  Node: Author,  Next: Credits,  Prev: Contributions,  Up: Top

Author
======

 My real name is Jean-Pierre Delprat but you can call me Jeepy or JP or
whatever you want. I was born in 1971 in a small village in France and I
started programming when I was 12.

 I started developing JPTUI in December, 1994, for my personal use.  After I
bought a modem card and I found a good ISP, I decided to release my library
on the web as a freeware on April, 1996.

 I live near Paris in France, English isn't my mother tongue and I haven't
said a word in English for many years. So excuse me if my English is not as
good as I would like.

 If you have some questions, problems or suggestions, send me an email so
that I can help you or inform you of new releases.


My email address is : jpdelprat@teaser.fr
My web home page is : www.teaser.fr/~jpdelprat


File: jptui.info,  Node: Credits,  Next: What's new,  Prev: Author,  Up: Top

Credits
=======

 Credits go to :


+ Lee Braiden

  for the first documentation of JPTUI (version 3.1)

+ Haruhiko Okumura

  for LZSS and LZARI compression/decompression routines

+ Ren‚ Olsthoorn

  for EXEDAT

+ Al Steven/Dr Dobb's Journal

  for huffman encoding/decoding routines and some ideas for
  the help system

+ Michael Mauch

  for the converter from the source files of JPTUI help files to
  texinfo/info files

+ All the persons who have helped me to write and test JPTUI


File: jptui.info,  Node: What's new,  Next: Files,  Prev: Credits,  Up: Top

What's new
==========


- JPTUI 4.0k (28-NOV-98) -----------------------------------------------

+ Changes
  > The source code is now included

+ Fixed bugs
  > The IDE file for JPDEMO.EXE  was not valid (invalid memory model for
    the target). This file is not provided any more.
  > Mistake in the documentation : huge model is -mh (not -ml)


- JPTUI 4.0j (13-JUL-98) -----------------------------------------------

+ Changes
  > Added 9x... fonts for Greek language

+ API Changes
  > Minor changes (some private methods are now protected)


- JPTUI 4.0i (10-JUN-98) -----------------------------------------------

+ New features
  > Partial support for  Greek language (only upper  case characters and
    no shortcuts)

+ Changes
  > The DJGPP  version is now  compiled  with gcc  2.8.1 instead  of gcc
    2.7.2
  > In the DJGPP  version, JPDEMO  makefile has been updated  to be used
    with gcc 2.8.1
  > Minor changes required by David JD Bell 's TUIMaker

+ Fixed bugs
  > If you  call the  'FileSelectionBox'  function  without  providing a
    'ok_button_caption' argument which  is different from "", the 'Open'
    button caption disappears when highlighting a file

+ API Changes
  > added methods :
    . TLabel : m_get_text()

- JPTUI 4.0h (11-MAY-98) -----------------------------------------------

+ Changes
  > Minor changes required by David JD Bell 's TUIMaker

+ Fixed bugs
  > The program may crash if you insert some text in a TTextZone at line
                                                                          1

- JPTUI 4.0g (23-APR-98) -----------------------------------------------

+ New features
  > Support for Dutch language

+ Changes
  > JPTUI  now verifies  that  vocabulary  files  don't contain  several
    strings with the same number
  > JPTUI only declares MIN and MAX macros if they don't already exist

+ Fixed bugs
  > Bug in the MessageBox function with the MB_RETRYCANCEL buttons
  > JPTUI crashes  if you  define a function to  call when an  object is
    opened and you use display functions in this callback

- JPTUI 4.0f (21-FEB-98) -----------------------------------------------

+ Fixed bugs
  > Bug in FileSelectionBox when the provided mask designates a relative
                                                                       path
  > When using the standard  font, the text cursor might  appear in some
    unproper situations

+ Changes
  >  The mask of the file selection box can be a file name (without wild
     card)
  >  JPTUI doesn't require a VGA card anymore

- JPTUI 4.0e (04-DEC-97) -----------------------------------------------

+ Fixed bugs
  > JPRefresh() was uselessly called by TList in some cases
  > JPRefresh() was missing in some cases
  > One  of the  variables used  by  the mouse  interrupt wasn't  locked
    (DJGPP version)
  > In THelpTextZone (and JPHELP.EXE), the program crashed when the user
    double_clicked in the text zone, beyond the end of the text
  > The help compiler now sorts the  index by alphabetical order and not
    by ASCII order.

+ Changes
  >  In the  DJGPP version,  documentation  is  also provided  in 'info'
                                                                     format
  >  The  caption of  the 'ok' button  in the file  selection box varies
     depending of the selected item of the list

- JPTUI 4.0d (20-Sep-97) -----------------------------------------------

+ New features
  > puth-buttons can have no shadow, only an horizontal shadow or a
    vertical one, or both

+ Fixed bugs
  > German vocabulary has been fixed

+ Changes
  > minor enhancements in TTextZone
  > new types :
    . TShadowChoice

- JPTUI 4.0c (30-Jul-97) -----------------------------------------------

+ Fixed bugs
  > the default button of  the window wasn't the  default button anymore
    if  you  used 'm_set_focus' on   another  object (different  from  a
    button) before opening the window for the second time

+ Changes
  > a shortcut is now ignored if it  corresponds to a special key of the
    object  which  has the  focus (this  key  is  now processed  by  the
    object)

- JPTUI 4.0b (05-Jul-97) -----------------------------------------------

+ New features
  > input Boxes can now be used to enter a password

+ Changes
  > the Borland version  is now compiled in huge model  (don't forget to
    change your configuration)
  > the 'GetMouseState'  and 'WaitMouseLeftButtonRelease'  functions can
    now be called when you have temporary closed the JPTUI screen
  > when you insert some text in a  TTextZone at the current position of
    the cursor (with the paste function  for instance), and some text is
    currently selected, this text is cleared first

- JPTUI 4.0a (23-Jun-97) -----------------------------------------------

+ Fixed bugs
  > important bug in JPTUI  4.0 : the program hangs if you open a window
    whereas the active window is modal
  > due to a bug in Windows 95 API, GetCurrentDir() (and getcwd()) could
    give wrong  with long  file names in some  cases, which  might cause
    problems with the file selection box (DJGPP version only)

- JPTUI 4.0  (22-Jun-97) -----------------------------------------------

+ New features
  > hypertext help system
  > you can now ask JPTUI to process events once (in long callbacks for
    instance)
  > support for EXEDAT arithmetic compression
  > support for Italian and Spanish languages
  > the close button of a window  (in the top-left corner of the window)
    can be pressed with the keys 'ALT+F4'

+ Fixed bugs
  > problems due  to a confusion  between giving the  focus to an object
    (which  belongs  to  a  window  which can  be  active  or  not)  and
    activating a window
  > problems with the text cursor in text zones
  > tab characters badly interpreted by TTextZones
  > minor bugs fixed

+ Changes
  > documentation is now provided in JPTUI help file format and ascii
                                                                     format

+ API Changes
  > added callbacks :
    . TTextZone : cursor_pos_changed_callback
  > added methods :
    . TWindow : m_is_active()
    . TTextZone : m_get_text_rel_x()
    . TTextZone : m_get_text_rel_y()
    . TTextZone : m_get_text_width()
    . TTextZone : m_get_text_height()
    . TTextZone : m_get_first_visible_col()
    . TTextZone : m_get_first_visible_line
  > changed methods :
    . TWindow : m_activate() now returns a boolean
  > changed functions :
    . FullPath() now returns a boolean
  > renamed types :
    . TStyle renamed to TGaugeStyle
  > added new alignments methods to TWindow::m_put_caption()

- JPTUI 3.8  (15-Feb-97) -----------------------------------------------

+ New features
  > JPTUI can now be run in a Dos box under Windows
  > JPTUI can now use the standard font
  > the message box can emit a sound when it opens
  > TTextZone can now read text containing some tab characters
  > The sources of FileSelectionBox() and MessageBox() are now
    provided with the library

+ Fixed bugs
  > in JPTUI 3.7, the TPasswordEditZone class was missing in the Borland
                                                                    library
  > rewrote the kbhit()  function which fails when the  user hits CTRL-S
    and pauses the application
  > some callbacks  in  TLists  and  TTextZones  (and  derived  classes)
    weren't called in some cases
  > very  old  and numerous  bugs  in  TTextZones including  text  copy,
    horizontal scrollbar...
  > minor bugs fixed

+ Changes
  > rewrote some routines of TTextZones
  > rewrote the PlaySound routine to make it easier to add new sounds
  > smoothed the beginnings of scrollings
  > files are now open in shared mode
  > when the user opens then closes a menu,  the message in the info bar
    of the window is no longer lost
  > when you call TWindow::m_open() and the window is already  open, the
    window now becomes active (and is brought to front).
  > minor enhancements

+ API Changes
  > added classes :
    . TFileListBox
  > added callbacks :
    . TTextZone : cursor_col_changed_callback
                                               cursor_line_changed_callback
    . TObject   : opened_callback
                                                            closed_callback
  > added methods :
    . TMenu::m_get_menu_bar()
    . TMenu::m_close()
    . TMenu::m_open()
    . TWindow::m_get_info_message()
    . TTextZone::m_get_tab_size()
    . TTextZone::m_set_tab_size()
    . TApplication::m_redraw_windows()
  > added function :
    . KeyPressed()
    . RunningUnderWindows()
    . SetDosBoxMode()
    . SetFullScreenMode()
    . GetFont()
    . SetFont()
    . SetMousePointerAspect()
  > removed function :
    . GraphicalMousePointer() (use SetMousePointerAspect() instead)
  > added types :
    . TFont
    . TMousePointerAspect

- JPTUI 3.7  (26-Nov-96) -----------------------------------------------

+ Fixed bugs
  > problems with file dialog box
    . drive detection in a network environment
    . invalid directories badly analysed by the Borland version
    . too long  directories/filenames in  path with the  Borland version
      make the program hang
    . using the '/'  character in paths  with the Borland  version makes
      the program hang
  > the 'DriveExists' function gave  incorrect results with local drives
    in a network environment
  > the MB_DEFBUTTONi attribute of the 'MessageBox' function didn't work
  > minor fixes

+ Changes
  > when you open a window, the focus goes to the default push-button

- JPTUI 3.6  (13-Nov-96) -----------------------------------------------

+ New features
  > new class :
    . TPasswordEditZone :  like TEditZone except that  each character of
      the zone is displayed as a '*'
  > new function :
    . FullPathOfFileInExeDir :  returns the full path  of a file located
      in the directory of your .exe file

+ Fixed bugs
  > the file selection box didn't detect network drives
  > the 'DriveExists' function returned FALSE for a network drive
  > possible memory allocation error  when a TEditZone displays an error
    dialog box before and after a change of language
  > wrong display of horizontal scrollbars
  > scrollbars could hang if they were too little on screen

+ Changes
  > TTextZones can now  have a vertical  and/or a horizontal scrollbars,
    or none
  > minor changes : behaviour of the cursor in TTextZones...
  > changed function declarations :
    .TTextZone(...)
  > new types :
    . TScrollbarChoice

- JPTUI 3.5  (05-Oct-96) -----------------------------------------------

+ New features
  > Borland C++ 4.52 version

+ Fixed bugs
  > in TEditZones, the <DEL> key deleted two characters instead of one
  > TTabGroup::m_set_focus  didn't give the  focus to its  first element
    if the TabGroup already had the focus

+ Changes
  > An  error  code is  provided  for  most  of  the "abnormal   program
    terminations"  due to  debugging  macros. For  each of this  code, a
    short explanation can be found in the file DEBUG.TXT

- JPTUI 3.4  (01-Aug-96) -----------------------------------------------

+ New features
  > support for any  text mode which uses a 8x16, 9x16,  8x14, 9x14, 8x8
    or 9x8 font  (with graphical or  text mouse pointer  in any of these
    modes, including modes which are not supported by mouse driver)

+ Fixed bugs
  > mouse code is now locked to avoid problems in case of paging
  > dialog boxes (MessageBox, InputBox and FileSelectionBox) now set the
    mouse pointer to MP_ARROW and restore the previous pointer when they
    are closed
  > minor bugs fixed and improvements

+ Changes
  > mouse is no longer required to start
  > you can choose the captions of the ok and cancel buttons in the file
    selection dialog
  > memory display functions (DEBUG_SHOW_MEMORY) in debug version
  > FatalError() now aborts (doesn't exit anymore)
  > JPTUI data files have changed :
    . removed font (JPTUI.FNT)
    . added fonts and mouse pointers  (JP8x8.FNT, JP9x8.FNT, JP8x14.FNT,
      JP9x14.FNT,  JP8x16.FNT,  JP9x16.FNT,  JP8x8.PTR,  JP8x14.PTR  and
      JP8x16.PTR)
  > you can know close a window, open a menu... even if the object which
    has the focus refuses to lose it

+ API Changes
  > changed function declarations :
    . TWindow::m_close
    . TEditZone.m_string_valid is now a public method
  > removed functions :
    . SaveScreen()
    . RestoreScreen()
  > added functions :
    . JPRefreshAll()                                (JPAppli.h)
      (=TApplication::m_refresh_all())              (TApplication.h)
    . SetTextMode()                                 (Screen.h)
    . SetUserTextMode()                             (Screen.h)
    . GetTextMode()                                 (Screen.h)
    . GetScreenWidth()                              (Screen.h)
    . GetScreenHeight()                             (Screen.h)
    . GetFontHeight()                               (Screen.h)
    . GetFontWidth()                                (Screen.h)
    . GetMousePointer()                             (Mouse.h)
  > added constants :
    . TEXTMODE_...                                  (Screen.h)
  > renamed constants :
    . MC_ (Mouse Cursor) renamed                    (Mouse.h)
      to MP_ (Mouse Pointer)
  > removed constants :
    . SCREEN_WIDTH                                  (Screen.h)
    . SCREEN_HEIGHT                                 (Screen.h)

- JPTUI 3.3  (13-Jul-96) -----------------------------------------------

+ New features
  > data file  support (in  the executable  directory,  or in  an exedat
    archive  located  in  the  executable directory  or  linked  to  the
    executable file)
  > multi-language support
  > choice between graphical mouse pointer and textual one at any time
  > string checking can be disabled in TEditZones

+ Fixed bugs
  > bug when trying to  move a window which is not  movable when another
    window is behind it
  > TList::m_enable_item() fixed
  > IsAltKey() (Keyboard.h) fixed
  > ALT-BACKSPACE in numerical TEditZones
  > minor bugs fixed and improvements

+ API Changes
  > changed function declarations :
    . TApplication::TApplication                    (TApplication.h)
  > removed functions :
    . TextWarning()                                 (Errors.h)
  > added functions :
    . AbortProgram()               		      (Errors.h)
    . GetLanguage()                		      (Vocab.h)
    . LoadVocabulary()             		      (Vocab.h)
    . FreeVocabulary()             		      (Vocab.h)
    . GetString()                                   (Vocab.h)
    . LoadDataFile()                                (JPData.h)
    . GetInvalidDataFileMessage()                   (JPData.h)
    . GraphicalMousePointer()                       (Mouse.h)
    . TEditZone::m_enable_string_checking()
    . TEditZone::m_disable_string_checking()
  > renamed functions :
    . SetMouseCursor() renamed to SetMousePointer() (Mouse.h)
  > renamed types :
    . TMouseCursor renamed to TMousePointer         (Mouse.h)

- JPTUI 3.2  (30-Jun-96) -----------------------------------------------

+ New features
  > file selection box (cf. FileBox.h)
  > items can be added to a list at a specified position
  > new callback in TComboBox : called when a choice is validated
  > constants in FILES.H :  max length of the  different components of a
                                                                       path

+ Fixed bugs
  > in TComboBox
    . edit-zone might not  be updated when the  selection changed in the
                                                                       list

+ Changes
  > JPTUI now looks  for JPTUI.FNT in  the executable  directory (not in
    search path)
  > critical error is always disabled
  > in edit-zones, ALT-BACKSPACE is now a toggle
  > selected item color in  lists -> you  can now see if  a list has the
                                                                      focus
  > changed function declarations :
    . TList::TList
    . TSimpleList::TSimpleList
  > removed functions :
    . EnableCriticalError
    . DisableCriticalError
    . List access functions of TComboBox
  > added functions :
    . TComboBox::m_get_list()
    . TComboBox::m_set_string_validated_callback()
    . TSimpleList::m_insert_item()
    . TMenu::m_insert_item()
    . TWindow::m_get_previous_focused_object()
    . EndOfString()
    . FullPath()
    . DriveExists()
    . GetCurrentDir()
    . FileSelectionBox()

- JPTUI 3.1  (06-Jun-96) -----------------------------------------------

+ New features
  > combo-boxes
  > windows :
    . modal/modeless windows
    . movable/not movable windows
    . the active window can be changed by clicking or ALT-F6 (unless the
      active window is modal)
    . information bar
  > lists (TListBox, TMenu...) :
    . each item in a list can be defined as a toggle or not
    . a menu item can be automatically toggled (checked/unchecked)
    . menu items can have shortcuts
    . menu items  can display  help messages in  the window  information
                                                                        bar
  > push-buttons :
    . when buttons are  pushed with a key,  they are only  released when
      the pressed key is released
  > text modification of edit-zones and text-zones can be prevented
  > disabled ctrl-break in non-debug version
  > critical error (int 0x24) can be disabled

+ Fixed bugs
  > fixed several minor bugs
  > a window  close button  could be pressed  even if the  object of the
    window which has the focus refused to lose it

+ Changes
  > several minor changes
  > new class :
    . TSimpleList
  > removed functions  :
    . TObject::m_hook_events()
    . TObject::m_unhook_events()
    . JPCloseWindows()
    . JPRefreshOnRetrace()
  > added functions :
    . TEditZone::m_select_all()
    . TList::m_get_item_index()
    . WaitKeyRelease()
  > windows :
    . closing may be forced, even if the  object of the window which has
      the  focus refuse to lose it
  > lists (TListBox, Tmenu...)
    . list items are defined differently (more freedom for each item)
  > refresh is always done on retrace
  > renamed jptui.a to libjptui.a
  > modified keyboard  routines -> one  keycode for each  combination of
                                                                       keys

- JPTUI 3.0  (20-Apr-96) -----------------------------------------------

+ First public release

- JPTUI 1.0  (02-Mar-96) -----------------------------------------------

+ First version, not publicly released


File: jptui.info,  Node: Files,  Next: Technical Information,  Prev: What's new,  Up: Top

Files
=====

 The following files are created when you install JPTUI :


- JPTUI Introduction ---------------------------------------------------

+ FILE_ID.DIZ             : Short JPTUI description
+ README.TXT              : Quick start instructions

- JPTUI Demo -----------------------------------------------------------

+ DEMO/MAKEDEMO.BAT       : To build the demo
+ DEMO/JPDEMO.SRC         : Source file of the hypertext help file
+ DEMO/JPDEMO.CPP         : Source file ot the program
+ DEMO/VOCAB.xxx          : Vocabulary files (multi-language support)
+ DEMO/...                : Misc files

- JPTUI Documentation --------------------------------------------------

+ DOCS/JPDOC.BAT          : To read the hypertext JPTUI documentation
+ DOCS/JPTUI.HLP          : Hypertext JPTUI documentation
+ DOCS/JPTUI.TXT          : Ascii JPTUI documentation

- Debug Version of the Library -----------------------------------------

+ LIBS/DEBUG/JPTUI.H      : JPTUI header file
+ LIBS/DEBUG/JPTUI.DAT    : JPTUI data files
+ LIBS/DEBUG/JPTUI.LIB    : Borland library (Borland version only)
+ LIBS/DEBUG/LIBJPTUI.A   : DJGPP library (DJGPP version only)

- Release Version of the Library ---------------------------------------

+ LIBS/NODEBUG/JPTUI.H    : JPTUI header file
+ LIBS/NODEBUG/JPTUI.DAT  : JPTUI data files
+ LIBS/NODEBUG/JPTUI.LIB  : Borland library (Borland version only)
+ LIBS/NODEBUG/LIBJPTUI.A : DJGPP library (DJGPP version only)

- Some source code from the JPTUI library ------------------------------

+ SRC/...                 : Source code for MessageBox and
			    FileSelectionBox functions

- JPTUI Tools ----------------------------------------------------------

+ TOOLS/EXEDAT.EXE	  : EXEDAT program by Ren‚ Olsthoorn (*note Credits::.)			    to create an archive (JPTUI.DAT)
			    of data files
+ TOOLS/CONNECT.EXE	  : CONNECT program by Ren‚ Olsthoorn (*note Credits::.)			    to link the archive created with EXEDAT to
			    your .exe file

+ TOOLS/JPHC.EXE          : JPTUI Help Compiler (JPHC /? for more info)
+ TOOLS/JPHELP.EXE        : JPTUI Help Viewer (JPHELP /? for more info)


File: jptui.info,  Node: Technical Information,  Next: Debug,  Prev: Files,  Up: Top

Technical Information
=====================

 JPTUI libraries are available for the following compilers :


+ DJGPP

  The DJGPP version of JPTUI has been compiled with DJGPP 2.0.1 (gcc
  2.8.1).

+ Borland C++

  The Borland version of JPTUI has been compiled with Borland C++ 4.52
  using the following options :

  > Memory model      : huge (-mh),
  > Alignment         : word alignment (-a),
  > Identifier length : 250 (-i250).

  Any program written JPTUI must be compiled with the same options.
  Borland JPTUI libraries can also be used with Borland C++ 4.0 and
  5.0 (but are not compatible with Turbo or Borland C++ 3.1).


File: jptui.info,  Node: Debug,  Next: FAQ,  Prev: Technical Information,  Up: Top

Debug
=====


- JPTUI Versions -------------------------------------------------------

Two versions of JPTUI are provided for each supported compiler :

+ A 'DEBUG' version

  You should use this version while developping :
  > it contains many tests which are in theory 'useless' and stops the
    program in in case of unexpected problems (invalid argument,
    unexpected situation...),
  > it provides macros (*note Debug Macros::.) to implement such tests in your code,
  > it gives the possibility to display available memory (*note Debug Macros::.) at the top of
    the screen while your program is running

+ A 'RELEASE' version

  You may use this version when your program has been fully tested :
  > it contains no such tests
  > it is smaller than the 'debug' version

- Abnormal program terminations ----------------------------------------

If you use the 'debug' version of JPTUI, and the program is stopped
due to an unexpected problem, you can get the following message :

Abnormal program termination ('Error code') :
'Filename' ('Line')

The different error codes are described below.

+   1 : Can't add an element to an open window
+   2 : An element of the object being destructed hasn't been destructed
+   3 : Can't add an element to an object which is open or can't have
	child objects
+   4 : Can't remove an element from an open window
+   5 : Object without window
+   6 : Disabled element
+   7 : Only a tab can be added to a tab group
+   8 : No tab is visible
+   9 : Only one application can be declared
+  10 : An application must be declared before any window declaration
+  11 : A window must be closed before being destructed
+  12 : Can't add a menu to an open menu bar
+  13 : Invalid icon type
+  14 : Invalid item number
+  15 : A window can't refuse to take the focus
+  16 : The visible tab is not the good one
+  17 : A disabled push button can't be pressed
+  18 : The edit zone hasn't taken the focus again after the closing of
        the message box
+  19 : Invalid button type
+  20 : Invalid button number
+  21 : The application is destructed without being stopped or while
        some dialog boxes are running
+  22 : Before destructing the application, all windows must be closed
        and destructed
+  23 : The application can't be initialized more than once
+  24 : The application must be initialized before being ran
+  25 : A dialog box can't be run if the application hasn't been
                                                                initialized
+  26 : Invalid window number
+  27 : Invalid window height
+  28 : Invalid menu number
+  29 : The application must be initialized before opening a window
+  30 : Invalid object number
+  31 : Invalid line length
+  32 : Can't process events if the application hasn't been initialized


File: jptui.info,  Node: FAQ,  Next: Preprocessor Symbols,  Prev: Debug,  Up: Top

FAQ
===

 Don't forget to read the technical information (*note Technical
Information::.) and the notes about

* Menu:

* Debug::                                                           debugging
.


+ A class doesn't seem to have any of the functions I would expect. How
  do I get it to do what I need ?

  Very often, you will find that many functions available for a class
  are actually provided by one of it's base classes.  Refer to the base
  classes section of each class's documentation for further functions.

+ How can I start my application with a textual mouse pointer ?

  Just call SetMousePointerAspect(MPA_TEXTUAL) or
  SetMousePointerAspect(MPA_MOUSE_DRIVER) before calling JPInit().

+ How can I change the caption of an object at run-time ? I tried
  m_set_caption and it doesn't seem to work ?

  The m_set_caption method can only be used for objects who already have
  a caption. So if you want to change the caption of an object at
  run-time you have to define a caption when you declare this object
  (the " " for instance).

+ I want to test the contents of a TEditZone when it loses focus.  So I
  wrote a function and set it as the callback. If the contents of the
  field do not meet my standards, I want to show a message box
  (specifying incorrect data) and then I want the focus to return to the
  TEditZone. I can't figure out how to use the 'm_set_focus' method to
  accomplish this.

  You have to declare a new class derived from TEditZone with at least
  the following methods : m_string_valid() and m_get_error_message().
  > 'boolean m_string_valid(char *string)' returns a boolean value which
    indicates if 'string' is a valid string for the editzone. When a
    TEditZone loses the focus and this functions returns FALSE for the
    contents of the zone, a dialog box is open and then the focus
    returns to the TEditZone.
  > The message displayed in the dialog box is the string returned by
    the method m_get_error_message(). This method can use the
    f_error_message field to store the error message : this string is
    initialized to NULL in the constructor of TEditZone and freed
    (delete[]) in the destructor if it's different from NULL.

+ I've created a C++ class and I want to use one of its methods as a
  callback for JPTUI, but the compiler refuses.

  You cannot use pointers to methods like pointers to usual functions.
  The only way to get a pointer to a method is to declare this method
  as static. Unfortunately, when a method is static, it's common to all
  instances of its class, so it doesn't know which instance is supposed
  to receive the callback. Most of the time, this problem is solved by
  using the first argument of callbacks which is a pointer to the object
  which caused the callbacks.

+ I want to get a pointer to the window a button belongs to. My button
  belongs to a frame, which belongs to another frame which belongs to
  a window. Do I have to use the m_get_parent() method to go from my
  button to the window ?

  No. Each object knows which window it belongs to. Use m_get_window()
  on your button to get a pointer to its window.

+ Your demo program works without any other file in its directory, but
  my application refuse to be ran if JPTUI.DAT is not located if the
  same directory.

  JPTUI.DAT is an archive of compressed data files. You can add, change
  and remove files with the EXEDAT program. When JPTUI needs a data
  file, it tries to find it in the directory of the .exe file, then it
  looks for JPTUI.DAT. You may link JPTUI.DAT to the .exe file with the
  CONNECT program.

+ I was wondering if you can add an object in a window during
  run-time. I tried but I couldn't manage to make it visible.

  Compile your program with the debug version of the library and you'll
  have the answer. You cannot add an object to a window which is open.
  What you can try is closing the window, adding your object and opening
  your window again.

+ The documentation on how JPRun(), JPStop(), JPRunDialog() and related
  functions need to be more complete. I have tried to create my own
  dialog-box function but could not get things right.

  The source code of two message boxes are provided with the library.
  You can use them as examples.

+ I've downloaded your library and I have problems compiling the example
  with BC++ v5.0. If compiles fine when using your makedemo.bat file
  (after changing the directory names), but when I load the project file
  into the Integrated Development Environment, and try to compile, it
  gives me errors when linking.

  When importing BC++ 4.52 project files with BC++ 5.0, several
  compiling options are lost. Read the technical information to get
  some information about them.

+ PObject->m_get_window() does not always seem to point to the TWindow
  that I expect it to (with menus for instance). Can you explain this ?

  Each object must belong to a window in order to be displayed. If you
  declare an object without parent, a window is dynamically created.
  Windows are like screens : nothing can be drawn outside them.

  If you look at menus, they are drawn outside the window in which the
  menu bar appears. As a matter of fact, each menu has its own window
  (dynamically created by the menu), which is different than the window
  of its menu bar.

  You probably want to use : menu->m_get_menu_bar()->m_get_window()


+ Is there a way to be doing something and every once in a while call a
  function that checks if a user clicked a button or something. Like
  printing a file and checking if the user clicked the cancel button to
  stop printing.

  The main part of JPTUI is a loop in which events are regularly
  examined. If an event occurs, JPTUI handles this event and invokes
  callbacks relevant to this event. There is one particulier callback
  ("no event" callback) which is invoked at each iteration of the loop,
  even if no event occurs.

  while (1]
  {
    -> processes events
    -> invokes the "no event" callback
  }

  There are two solutions to your problem :

  1) Cut the function you want to be able to interrupt in small pieces
  that you execute in the "no event" callback (cf the
  'JPSetNoEventCallback' function). It's quite easy if your function is
  a loop.

  2) In your function, regularly call the 'JPProcessEvents' functions.
  This function execute an iteration of JPTUI's main loop. It processes
  events once, invokes the "no event"  callback than return.

  I personally advise the first solution because in that case, your
  function is called outside any other callback. With the second
  solution, your function is already called inside a callback and you
  ask JPTUI to handle other events and invoke other callbacks, whereas
  it hasn't finished to handle the first one.


File: jptui.info,  Node: Preprocessor Symbols,  Next: Datatypes,  Prev: FAQ,  Up: Top

Preprocessor Symbols
====================

* Menu:

* Boolean Definitions::                           Various boolean definitions
* Cursor Definitions::              Definitions for the various cursor styles
* Datatype Definitions::             Minimum and maximum values for datatypes
* EditZone Definitions::                              EditZone-related values
* File Definitions::                     Various definitions related to files
* Keycode Definitions::                 Identifiers for referring to each key
* Gauge Definitions::                       Various Gauge-related definitions
* InputBox Definitions::                 Various InputBox-related definitions
* Language Definitions::                         Language-related definitions
* List Definitions::                                 List-related definitions
* MessageBox Definitions::             Various MessageBox-related definitions
* Mouse Definitions::                           Symbols relating to the mouse
* Object Type Definitions::            Symbols to identify the various object
                                                                       types

* Menu:

* PushButton Type Definitions::        Special identifiers for various button
                                                                       types

* Menu:

* Screen Definitions::             Various definitions related to the display
* ScrollBar Definitions::                            ScrollBar-related values
* Shadow Definitions::                            Symbols telating to shadows
* Shortcut Definitions::           Identifiers for referring to shortcut keys
* Sound Definitions::                    Identifiers for each sound available
* Special Character Definitions::    Identifiers for the Graphical Characters
                                                                        used

* Menu:

* TextZone Definitions::                         TextZone-related definitions
* TList Attribute Definitions::                     Attributes for TListItems
* Window Definitions::                     Various Window-related identifiers


File: jptui.info,  Node: Datatypes,  Next: Structures,  Prev: Preprocessor Symbols,  Up: Top

Datatypes
=========

* Menu:

* String Datatypes::                                     String-related types


File: jptui.info,  Node: Structures,  Next: Global Variables,  Prev: Datatypes,  Up: Top

Structures
==========

* Menu:

* Keyboard Structures::                All public keyboard-related structures
* TList Structures::                      All public TList-related structures
* TMenu Structures::                      All public TMenu-related structures


File: jptui.info,  Node: Global Variables,  Next: Functions and Macros,  Prev: Structures,  Up: Top

Global Variables
================

 Technically, there are no global variables defined by JPTUI, but there is
one that you are required to define -- your application (ie, an instance of
the TApplication class). The name of this object doesn't matter (I suggest
you use the name of your program), since JPTUI allows you to access it using
a macro, called JPApplication.

 The actual macro is...

 #define JPApplication (TApplication::f_current_application)

 So, effectively, there is one global variable defined as...

 extern PApplication JPApplication;


File: jptui.info,  Node: Functions and Macros,  Next: Classes,  Prev: Global Variables,  Up: Top

Functions and Macros
====================

* Menu:

* Application Macros::                      Macros related to the application
* Character set Macros::                  Macros related to the character set
* MIN and MAX Macros::
* Caption Functions::                       Macros related to object captions
* Character set Functions::            Functions related to the character set
* Conversion Functions::               Conversion functions between different
                                                                       types

* Menu:

* Cursor Functions::                     Functions related to the text cursor
* Data file Functions::                   Functions related to resource files
* Debug Macros::                                  Macros useful for debugging
* Dialog Functions::                        Functions related to dialog boxes
* Error Functions::                     Functions to be used in case of error
* File Functions::                                 Functions related to files
* Keyboard Functions::                      Functions related to the keyboard
* Mouse Functions::                            Functions related to the mouse
* Screen Functions::                          Functions related to the screen
* Shadow Functions::                     Functions to be used to draw shadows
* Sound Functions::                       Functions to be used to emit sounds
* Text Functions::                   Functions related to the text of objects
* Video beam Functions::                  Functions related to the video beam
* Vocabulary Functions::                  Functions related to multi-language
                                                                     support

* Menu:

* Windows Functions::                  Functions related to Microsoft Windows


File: jptui.info,  Node: Classes,  Next: Boolean Definitions,  Prev: Functions and Macros,  Up: Top

Classes
=======

* Menu:

* TApplication::
* TCheckBox::
* TComboBox::
* TDecimalEditZone::
* TEditZone::
* TFileListBox::
* TFrame::
* TGauge::
* TGroup::
* THelpWindow::
* TIntegerEditZone::
* TLabel::
* TList::
* TListBox::
* TMenu::
* TMenuBar::
* TObject::
* TPasswordEditZone::
* TPushButton::
* TRadioButton::
* TRadioGroup::
* TScrollBar::
* TSimpleList::
* TTab::
* TTabGroup::
* TTextZone::
* TWindow::


File: jptui.info,  Node: Boolean Definitions,  Next: Cursor Definitions,  Prev: Classes,  Up: Preprocessor Symbols

Boolean Definitions
===================

 JPTUI defines various alternate identifiers for the two boolean states (ON
and OFF). These can be used instead of the generic TRUE and FALSE in order
to make it more obvious what they specify.

 For example, one of the arguments to the TWindow constructor is a boolean
value which allows you to specify whether the window would have an info bar.
Normally, if you specified an info bar, the constructor would just have the
argument TRUE as one of it's arguments, and you would probably not remember
what it meant if you read the code at a later date. By using the alternative
identifier "INFO_BAR", the code instantly becomes more readable.


+ FALSE / TRUE
+ DISABLED / ENABLED
+ NOT_CHECKED / CHECKED
+ NOT_SORTED / SORTED
+ NOT_MODAL / MODAL
+ NO_INFO_BAR / INFO_BAR
+ NOT_MOVABLE / MOVABLE
+ STRING_NEEDNT_TO_BE_IN_LIST / STRING_MUST_BE_IN_LIST


File: jptui.info,  Node: Cursor Definitions,  Next: Datatype Definitions,  Prev: Boolean Definitions,  Up: Preprocessor Symbols

Cursor Definitions
==================


+ RECOVER_CURSOR

  This is used to specify the 'Overwrite Mode' cursor.

+ INSERT_CURSOR

  Specifies the 'Insert Mode' cursor.


File: jptui.info,  Node: Datatype Definitions,  Next: EditZone Definitions,  Prev: Cursor Definitions,  Up: Preprocessor Symbols

Datatype Definitions
====================


- Ranges of Data Types -------------------------------------------------

+ MAXWORD

  This defines the maximum possible value for the 'word' data type.

- String to Number Conversion ------------------------------------------

+ LONG_MAX_LENGTH

  The maximum length of long integer's string-representation.

+ DOUBLE_MAX_LENGTH

  The maximum length of double's string-representation.

+ DOUBLE_NB_DIGITS

  The number of significant digits that will be recognised in a double's
  string-representation.


File: jptui.info,  Node: EditZone Definitions,  Next: File Definitions,  Prev: Datatype Definitions,  Up: Preprocessor Symbols

EditZone Definitions
====================


- Scrolling Speed ------------------------------------------------------

+ EDITZONE_SCROLL_SPEED

  This defines the speed at which text scrolls in an EditZone.  The
  value is measured in milliseconds.  The actual area which is moved in
  this time depends on the operation.  For example, scrolling with the
  scroll arrows will move one line in the specified time, while
  scrolling by clicking the empty part of a scrollbar will scroll one
  page in the same time.

+ EDITZONE_FIRST_SCROLL_SPEED

  This defines the delay between the first move of a scrolling and the
  other moves. This allows the user to make only one move by quickly
  clicking and releasing the mouse button.


File: jptui.info,  Node: File Definitions,  Next: Keycode Definitions,  Prev: EditZone Definitions,  Up: Preprocessor Symbols

File Definitions
================

 These constants define the maximal length of the buffers needed to hold the
differents components of a file name.


+ MAX_PATH

  Example : X:\DIR\SUBDIR\FILE.EXT

+ MAX_DRIVE

  Example : X:

+ MAX_DIR

  Example : \DIR\SUBDIR\

+ MAX_FILE

  Example : FILE.EXT

