tinywidget.rar tnw-tut.sgml

www.pudn.com > tinywidget.rar > tnw-tut.sgml

<!doctype linuxdoc system>

<article>



<title>The TinyWidgets Tutorial
<author><sl/Sunil Soman/, <tt/sunils@bikerider.com/
<sl/Amit Kulkarni/ ,<tt/kulkarniar@hotmail.com/
<sl/Navin Thadani/, <tt/navin@deathsdoor.com/
<date>v1.0, Sun Jan 21 2001
<abstract>
This document briefly decribes TinyWidgets. TinyWidgets is a Free Source widget set for the Nano-X API.
</abstract>


<toc>

<sect>Introduction

TinyWidgets is a Free Source Project licensed under the GPL. It is intended to be used with the Nano-X API, which is a part of Greg Haerr's <tt/&amt;lt;greg@censoft.com&amt;gt;/ <url url="http://www.microwindows.org" name="Microwindows"> project.
This document should (hopefully) be enough to get you started with writing your application using TinyWidgets.

<sect>Getting started

To begin our introduction to TinyWidgets, we'll start with the simplest program possible. This program will create a 200x200 pixel window.
<tscreen><code>
/* base.c */

#include <TinyWidgets/tnWidgets.h>

int main( int argc,
char *argv[] )
{
TN_WIDGETS *main_window,*window;

main_window = tnAppInitialize(argc, argv);

window = tnCreateWidget (TN_WINDOW,main_window,50,50,TN_HEIGHT,200, TN_WIDT
H,200,TN_END);
tnMainLoop ();

return(0);
}
/* example-end */
</code></tscreen>
You can compile the above program with gcc using:
<tscreen><verb>
> gcc base.c -o base -ltnW -lnano-X
</verb></tscreen>

All programs will of course include the header <tt/tnWidgets.h/ which declares the variables, functions, structures etc. that will be used in your TinyWidgets application.

The next line:
<tscreen><code>
tnAppInitialize (argc, argv);
</code></tscreen>
will be called in all TinyWidgets applications. This sets up a few things for us and then proceeds to call GrOpen() which opens a socket connection with the Nano-X server . This function initializes the library for use. As of yet there are no provisions for handling the command line parameters but it has been included for later implementation.

The next line creates and displays a window.
<tscreen><code>
window = tnCreateWidget (TN_WINDOW,main_window,50,50,TN_HEIGHT,200, TN_WIDTH,20
0,TN_END);
</code></tscreen>
The tnCreateWidget is a generalised function which accepts variable number of parameters. Only the first 4 parameters are mandatory. They are widget type, parent widget, xposition &amt; yposition relative to parent. The rest of the parameters are optional and default values will be taken if they are not specified. Also the optional parameters can be specified in any order but they have to be specified as pairs of (parameter type, value). For eg to specify the height of the widget you have got to specify it as TN_HEIGHT, 200. The argument list must be terminated with TN_END to indicate end of parameter list. The use of this function will be more clear with further examples.

The last line enters the tnWidgets main processing loop.
<tscreen><code>
tnMainLoop ();
</code></tscreen>
This is another call you will see in every TinyWidgets application. When control reaches this point, tnWidgets will sleep waiting for Nano-X events (such as button or key presses). In our simple example however, events are ignored.

<sect>The Widgets

<sect1>TN_WINDOW<label id="TN_WINDOW">

This is the Window widget. For every application you will need atleast one window. All other widgets can be added to a Window widget.

A Window widget can listen to the CLOSED event &amt; call the user callback for this event.

You can cause a window to become the main application window, by setting TN_APPWIN to 1 in it's create call. This will ensure that the connection to the server will be closed when this window is closed &amt; the application terminates.

A Window can take the following properties :
<itemize>
<item>TN_BGCOLOR : Background color for the window (defaults to grey).
<item>TN_CAPTION : The window title.
<item>TN_HEIGHT : The window height.
<item>TN_WIDTH : The window width.
<item>TN_APPWIN : The window is the main application window (this will cause the connection to the Nano-X server to be closed &amt; the application to terminate when the window is closed.
</itemize>

<sect1>TN_BUTTON<label id="TN_BUTTON">

This is the Push Button widget.

<sect1>TN_LABEL<label id="TN_LABEL">

This is the Label widget.

<sect1>TN_CHECKBUTTON<label id="TN_CHECKBUTTON">


<sect1>TN_RADIOBUTTONGROUP<label id="TN_RADIOBUTTONGROUP">


<sect1>TN_RADIOBUTTON<label id="TN_RADIOBUTTON">


<sect1>TN_TEXTBOX<label id="TN_TEXTBOX">


<sect1>TN_SCROLLBAR<label id="TN_SCROLLBAR">

This is the ScrollBar widget.

Utility functions :
<tscreen><code>int tnGetLastScrollEvent(TN_WIDGET *scrollbar)
</code></tscreen>
TODO
<tscreen><code>int tnGetThumbPosition(TN_WIDGET *scrollbar)
</code></tscreen>
<sect1>TN_PROGRESSBAR<label id="TN_PROGRESSBAR">

The progressbar widget. Currently two styles are supported :
<itemize>
<item>Continuous
<item>Discrete
</itemize>
The call to tnCreateWidget creates a continous progressbar by default. A discrete progressbar will be created if TN_DISCRETE is specified.

The following (optional) properties are associated with the progressbar:
<itemize>
<item>TN_STEPSIZE : The step size for the discrete progressbar.
<item>TN_FILLCOLOR : The fill color for the bar.
<item>TN_FONTNAME : The font to be used for the text which indicate completion status.
<item>TN_FONTSIZE : The font size for the above mentioned text.
</itemize>
Utility functions :
<tscreen><code>void tnProgressBarUpdate(TN_WIDGET *pbar, float value)
</code></tscreen>
Updates the progressbar value.

<sect1>TN_LISTBOX<label id="TN_LISTBOX">


<sect1>TN_PICTURE<label id="TN_PICTURE">

This is the picture widget and allows the user to display images(BMP, JPEG, GIF etc) in a picture container.
The following optional properties are associated with the Picture widget.
<itemize>
<item> TN_HEIGHT : The height of the container.
<item> TN_WIDTH : The width of the container.
<item> TN_FILENAME : The filename of the image to be displayed in the container. The full path of the filename must be specified.
<item> TN_STRETCH : This is a Boolean value. If True then the container will be resized to the size of the image to be displayed. If this value is false the image will be resized to the size of the container.
</itemize>

The following utility functions have been provided for the Picture widget :-
<tscreen> <code> int tnSetPicture(TN_WIDGET *picture, char *filename) </code></tscreen>
<quote> This functions loads the image specified by filename into the picture widget. It returns -1 in case of error. </quote>
<tscreen> <code> int tnSetPictureStretch(TN_WIDGET *picture,GR_BOOL stretch) </code> </tscreen>
<quote> This function sets the Stretch property of the picture widget. </quote>
<tscreen> <code> int tnPictureDup(TN_WIDGET *destpic,TN_WIDGET *srcpic) </code> </tscreen>
<quote> This function duplicates the image displayed in the srcpic widget into the destpic widget. This is especially useful in order to save memory. By using the Duplication of the image it is not loaded by the server again. </quote>

<sect1>TN_MENUBAR<label id="TN_MENUBAR">


<sect1>TN_POPUPMENU<label id="TN_POPUPMENU">


<sect1>TN_CASCADEDMENU<label id="TN_CASCADEDMENU">


<sect1>TN_MENUITEM<label id="TN_MENUITEM">


<sect>The TinyWidgets API

<sect1>tnAppInitialize

<tscreen><code>
TN_WIDGET * tnAppInitialize(int argc, char *argv[])
</code></tscreen>
Initializes various parameters of the internal state machine for Tiny Widgets and calls GrOpen to open a socket to Nano-X. It returns a pointer to TN_WIDGET which is supposed to be the main widget and should be used as parent to the main window widget that will be created. Takes parameters as argc and argv, but there is no provision as yet for parsing command line parameters. It will be implemented in future versions.
<sect1>tnCreateWidget

<tscreen><code>
TN_WIDGET * tnCreateWidget(TN_WIDGET_TYPE type,
TN_WIDGET *parent, int posx, int posy,...)
</code></tscreen>
Creates a widget specified by the type arguement and places it at position specified by posx, posy, relative to the parent widget specified by the parent arguement. The various types of widgets that can be created are:
<itemize>
<item><ref id="TN_WINDOW">: This creates a window widget which behaves as the container for all other widgets.
<item><ref id="TN_BUTTON">: This creates a push button. The parent for this must be a widget of type TN_WINDOW.
<item><ref id="TN_LABEL">: This is a static Label. Parent must be TN_WINDOW.
<item><ref id="TN_CHECKBUTTON">: This creates a check button widget.
<item><ref id="TN_RADIOBUTTONGROUP">: This creates a frame on the form which behaves as a container for radiobuttons.
<item><ref id="TN_RADIOBUTTON">: This creates a radiobutton. Within a radiobutton group only a single radiobutton can be active at any time. The parent for this widget must be widget of type TN_RADIOBUTTONGROUP.
<item><ref id="TN_TEXTBOX">: This creates a single or multi-line editable textbox with infinite text length.
<item><ref id="TN_SCROLLBAR">: This creates a scrollbar. Vertical or Horizontal scroll bars can be specified by an optinonal orientation arguement. By default a vertical scrollbar is created if the style arguement is not specified.
<item><ref id="TN_PROGRESSBAR">:
<item><ref id="TN_LISTBOX">:
<item><ref id="TN_PICTURE">:
<item><ref id="TN_MENUBAR">:
<item><ref id="TN_POPUPMENU">:
<item><ref id="TN_CASCADEDMENU">:
<item><ref id="TN_MENUITEM">:
</itemize>
There are various optional arguements that can be specified for every widget. The optional arguements have to be specified as a pair of values, the first specifying the type of arguement and the second the value. The various types of arguments that can be specified are:
<itemize>
<item>TN_FONTNAME : This specifies a font to be used for any text that is to be visible within the widget. The arguement is invalid for a widget like scrollbar where there is no text output.
<item>TN_FONTSIZE : This gives the size of the font to be used for text output.
<item>TN_BGCOLOR : This allows setting of the background color of the widget. The arguement following this should be of type GR_COLOR.
<item>TN_FGCOLOR
<item>TN_CAPTION
<item>TN_HEIGHT
<item>TN_WIDTH
<item>TN_DEFAULTTEXT
<item>TN_STYLE
<item>TN_MAXLENGTH
</itemize>
Not all arguments are valid for all widgets.

<sect>Examples

</article>