[Top] [Contents] [Index] [ ? ]

Libtui


Overview:

1. Libtui Developer Reference
2. Overview
3. Basics
4. Linking
5. Autoconf
6. Header Files
7. Required Calls
8. Interface
9. Core Functions
10. Windows
11. Creating and Destroying Windows
12. Manipulating Windows
13. Getting Window Information
14. Window Example
15. Menu System
16. Menubars
17. Menus
18. Menu Items
19. Menu Example
20. Implementation
21. Libtui Copying Conditions
22. Contributors
Index
Function Index
Data Type Index

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Libtui Developer Reference

This document is for developers of Libtui and developers that use Libtui in their product. The document's intent is to describe, in detail, the interface and implementation of the library.

$Revision: 1.7 $

2. Overview  What is Libtui?
3. Basics  How to use Libtui in your application.
8. Interface  Function-call interface of for Libtui.
20. Implementation  Some notes on the internals of Libtui.

21. Libtui Copying Conditions  License and copying information.
22. Contributors  People who have contributed to Libtui.

Index  Index of concepts.
Function Index  Index of function names.
Data Type Index  Index of data types.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Overview

Libtui is designed to be used as a helper library along the side of your curses-based applications. However, it can also be used as a layer on top of curses without needing to write any curses-related code. It is geared toward developing console applications. As such, it aims to include things like:

All Libtui interface functions are prefixed with `tui'. Internal Libtui functions are prefixed with `__tui'. As a user of Libtui, you will only be concerned with the interface functions, not the internal ones.

Most Libtui data structures are managed with a new and delete call. For example, to manage a tuiWindow you would use the following functions:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Basics

4. Linking  How to link Libtui
5. Autoconf  Rules for autoconf to detect Libtui.
6. Header Files  What headers to include.
7. Required Calls  Required actions before and after using Libtui.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Linking

To link Libtui with your application, use the following argument:

-ltui

For example:
 
$ gcc -o myapp myapp.c -ltui


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Autoconf

Place the following in your configure.in file:

 
AC_CHECK_LIB(tui, tuiExit,[
  LIBS="$LIBS -ltui"
],[
  AC_MSG_ERROR([

The Libtui library is needed for compiling xyz app. You can get it
at: http://www.wsmake.org/~mike/software/libtui/])
])


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Header Files

For access to all of Libtui's functionality in a portable way, include the "tui/tui.h" header file in your program:

 
#include <tui/tui.h>


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Required Calls

Libtui must be initialized before your application can use the available features. There are two ways to do this:

 
tuiInitMore(NULL);
or
 
tuiInit(NULL);

The tuiInitMore function handles curses initialization whereas tuiInit expects you to do it in your application. The parameter is a callback for internal errors so that you can clean up your application's state before quitting. Use NULL if you don't need that.

Now you can begin using Libtui features. As mentioned in the Overview section, each of the features has a start and end function. See section 2. Overview.

TODO: show examples, etc...

After the application is through running, it is recommended to call an exit function for Libtui if tuiInitMore was used to initialize libtui:

 
tuiExitMore(0);

The parameter is the error number. 0 represents success (no error).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Interface

9. Core Functions  
10. Windows  
15. Menu System  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Core Functions

The core functions represent critical access points into the Libtui library. They are defined in `tui/core.h' and are included by `tui/tui.h'.

Each core function is usually paired with a "More" version. These "More" versions perform the necessary curses calls for Libtui to function properly. Non-"More" versions are provided for when finer tuning of curses is desired.

Function: void tuiInitMore (void (*exitfunc)(int))
This function initializes Libtui and many common curses settings.

exitfunc is a callback used when an error occurs in Libtui or when tuiEnd or tuiEndMore is called. exitfunc may be NULL. When exitfunc is called from Libtui, the integer passed is 0 on success (no error), or the value of errno.

Function: void tuiExitMore (int error)
This function cleans up any leftover issues in Libtui and shuts down curses.

If error is non-0, the callback set by tuiInitMore or tuiInit is called with that value (provided that the callback is not NULL).

Function: void tuiRefreshMore (void)
This function should be called whenever you want a screen update of Libtui components. It flushes the buffer with the curses doupdate function.

Function: void tuiInit (void (*exitfunc)(int))
This function initializes Libtui but does not do any curses initialization.

exitfunc is a callback used when an error occurs in Libtui or when tuiEnd or tuiEndMore is called. exitfunc may be NULL. When exitfunc is called from Libtui, the integer passed is 0 on success (no error), or the value of errno.

Function: void tuiExit (int error)
This function cleans up any leftover issues in Libtui but does not shut down curses.

If error is non-0, the callback set by tuiInitMore or tuiInit is called with that value (provided that the callback is not NULL).

Function: void tuiRefresh (void)
This function should be called whenever you want a screen update of Libtui components. It does not flush the buffer with the curses doupdate function.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Windows

11. Creating and Destroying Windows  
12. Manipulating Windows  
13. Getting Window Information  
14. Window Example  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Creating and Destroying Windows

Function: tuiWindow tuiWinNew (tuiWindow win, int x, int y, int w, int h, int vx, int vy, int vw, int vh, void (*draw)(tuiWindow), void (*bdraw)(tuiWindow))
This function creates a tuiWindow and returns it. When tuiWindows are created, they are added to an internal list which will be used when a refresh of the screen is requested. See section 9. Core Functions.

x (column) and y (row) are the screen position for the window. If x or y is greater than 0, the value is used directly for the screen position. If x or y is less than 0, the absolute value is used as a percentage of screen width/height.

w (width) and h (height) specify the window's size. if w or h is greater than 0, the value is used directly for the size. If w or h is equal to 0, then the current maximum width or height of the screen is used, respectively. If w or h is less than 0, the absolute value is used as a percentage of the current screen width or height respectively.

vw (virtual width) and vh (virtual height) specify the window buffer size. vw and vh are treated the same as w and h.

draw is a callback that is called from tuiWindowRefresh.

If bdraw is non-NULL, an additional window will be created around the window being created. The bdraw callback is called from tuiWindowRefresh before the draw callback for it's associated window. If bdraw is NULL, no border will be created, and no callback will happen for the border.

Function: tuiWindow tuiWinDelete (tuiWindow win)
This function will release the memory used by the passed tuiWindow. It also removes the window from the internal draw list, so it is transparent to refresh requests.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Manipulating Windows

Function: void tuiWinScroll (tuiWindow win, int direction)
This function scrolls the buffer in a window in a direction specified by direction. The direction types are:

`TUIWINSCROLLUP'
scrolls up
`TUIWINSCROLLDOWN'
scrolls down
`TUIWINSCROLLLEFT'
scrolls left
`TUIWINSCROLLRIGHT'
scrolls right
`TUIWINSCROLLTOP'
scrolls to top of the window's buffer
`TUIWINSCROLLBOT'
scrolls to the bottom of the window's buffer. the bottom of the buffer is shown at the bottom of the window's visual area.

Function: void tuiWinScrollTo (tuiWindow win, int location)
This function scrolls a window's buffer to a specific location where location is a value greater than 0 and less than the buffer size. It will only scroll if location is not already in the view area.

Function: void tuiWinResize (tuiWindow win, int w, int h)
This function resizes the given tuiWindow to a new width and height.

Function: void tuiWinResizeV (tuiWindow win, int vw, int vh)
This function resizes the given tuiWindow's buffer to a new width and height.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. Getting Window Information

Function: void tuiWinList (void)
This functions lists the tuiWindows that libtui knows about. It prints address, location, and size information to stderr.

Function: void tuiWinScreenDump (FILE *out)
This function reads all of the tuiWindow buffers and prints them to the out file pointer. The file pointer must already be open with write capabilities.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14. Window Example


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15. Menu System

To create a menu system, you begin by creating a tuiMenuBar. Then you can create tuiMenus for the menubar. Then tuiMenuItems can be created for each menu.

16. Menubars  
17. Menus  
18. Menu Items  
19. Menu Example  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

16. Menubars

Function: tuiMenuBar tuiMenuBarNew (int pos, chtype at)
This functions creates a tuiMenuBar and returns it. The pos parameter specifies which side of the screen the menubar should be. Currently only TUIMENUBAR_TOP for the top of the screen is supported. TUIMENUBAR_BOT will be supported in the future for having a menubar on the bottom of the screen. The at parameter is a attribute specifier for the menubar. This parameter is directly related to the Curses attribute types.

Function: tuiMenuBar tuiMenuBarDelete (tuiMenuBar mb)
This function deletes the memory claimed by the tuiMenuBar at mb. It also causes any attached menus to be menubarless.

Function: void tuiMenuBarMoveMenu (tuiMenuBar mb, tuiMenu m, int pos)
This function moves a menu to a new menu bar. mb is the menubar to move to, m is the menu being moved, and pos is the position on the menubar to move to. FIXME: xref to position types


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

17. Menus


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

18. Menu Items


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19. Menu Example


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

20. Implementation

TODO: put notes about internals here


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

21. Libtui Copying Conditions

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

This library 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 library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

22. Contributors

Hey you! Want to help with this document and have your name put in here? Send updates to mike@wsmake.org.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   A   B   C   G   L   M   R   W  

Index Entry Section

A
Autoconf5. Autoconf

B
Basics3. Basics

C
Core9. Core Functions
Creating and Destroying Windows11. Creating and Destroying Windows

G
Getting Window Information13. Getting Window Information

L
Libtui6. Header Files
Linking4. Linking

M
Manipulating Windows12. Manipulating Windows
Menu Example19. Menu Example
Menu Items18. Menu Items
Menu System15. Menu System
Menubars16. Menubars
Menus17. Menus

R
Required calls7. Required Calls

W
Window Example14. Window Example
Windows10. Windows

Jump to:   A   B   C   G   L   M   R   W  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Function Index

Jump to:   T  

Index Entry Section

T
tuiExit9. Core Functions
tuiExit9. Core Functions
tuiExitMore9. Core Functions
tuiExitMore9. Core Functions
tuiInit9. Core Functions
tuiInit9. Core Functions
tuiInitMore9. Core Functions
tuiInitMore9. Core Functions
tuiMenuBarActivateMenu16. Menubars
tuiMenuBarDelete16. Menubars
tuiMenuBarDelete16. Menubars
tuiMenuBarGetActiveMenu16. Menubars
tuiMenuBarMoveMenu16. Menubars
tuiMenuBarMoveMenu16. Menubars
tuiMenuBarNew16. Menubars
tuiMenuBarNew16. Menubars
tuiMenuBarRemoveMenu16. Menubars
tuiMenuDelete17. Menus
tuiMenuItemFree18. Menu Items
tuiMenuItemMake18. Menu Items
tuiMenuNew17. Menus
tuiMenuPopItem17. Menus
tuiMenuPushItem17. Menus
tuiRefresh9. Core Functions
tuiRefresh9. Core Functions
tuiRefreshMore9. Core Functions
tuiRefreshMore9. Core Functions
tuiWinDelete11. Creating and Destroying Windows
tuiWinDelete11. Creating and Destroying Windows
tuiWinList13. Getting Window Information
tuiWinList13. Getting Window Information
tuiWinNew11. Creating and Destroying Windows
tuiWinNew11. Creating and Destroying Windows
tuiWinResize12. Manipulating Windows
tuiWinResize12. Manipulating Windows
tuiWinResizeV12. Manipulating Windows
tuiWinResizeV12. Manipulating Windows
tuiWinScreenDump13. Getting Window Information
tuiWinScreenDump13. Getting Window Information
tuiWinScroll12. Manipulating Windows
tuiWinScroll12. Manipulating Windows
TUIWINSCROLLBOT12. Manipulating Windows
TUIWINSCROLLDOWN12. Manipulating Windows
TUIWINSCROLLLEFT12. Manipulating Windows
TUIWINSCROLLRIGHT12. Manipulating Windows
tuiWinScrollTo12. Manipulating Windows
tuiWinScrollTo12. Manipulating Windows
TUIWINSCROLLTOP12. Manipulating Windows
TUIWINSCROLLUP12. Manipulating Windows

Jump to:   T  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Data Type Index


[Top] [Contents] [Index] [ ? ]

Table of Contents

1. Libtui Developer Reference
2. Overview
3. Basics
4. Linking
5. Autoconf
6. Header Files
7. Required Calls
8. Interface
9. Core Functions
10. Windows
11. Creating and Destroying Windows
12. Manipulating Windows
13. Getting Window Information
14. Window Example
15. Menu System
16. Menubars
17. Menus
18. Menu Items
19. Menu Example
20. Implementation
21. Libtui Copying Conditions
22. Contributors
Index
Function Index
Data Type Index

[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Libtui Developer Reference
2. Overview
3. Basics
4. Linking
5. Autoconf
6. Header Files
7. Required Calls
8. Interface
9. Core Functions
10. Windows
11. Creating and Destroying Windows
12. Manipulating Windows
13. Getting Window Information
14. Window Example
15. Menu System
16. Menubars
17. Menus
18. Menu Items
19. Menu Example
20. Implementation
21. Libtui Copying Conditions
22. Contributors
Index
Function Index
Data Type Index

[Top] [Contents] [Index] [ ? ]

About this document

This document was generated using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by on May, 16 2001 using texi2html