Next Previous Contents

5. The Widgets

5.1 TN_WINDOW

Introduction

This is the Window widget. For every application you will need atleast one window. All other widgets can be added to a Window widget. The parent for the window widget must be the widget returned by tnAppInitialize.

Specifications

A Window can take the following optional properties in the call to tnCreateWidget.

Examples:

A window specification with a window title "My App"


window1 = tnCreateWidget(TN_WINDOW,main_widget,50,50,TN_HEIGHT,200,TN_WIDTH,200,TN_CAPTION,"My App",TN_END);

Callbacks

The following callbacks can be specified when calling tnRegisterCallBack for a window.

Utility Functions

The following utility functions have been provided to manipulate the properties of the window


tnGetClickedPos(TN_WIDGET *window, int *x, int *y)

Description : Returns the x and y co-ordinates where the last clicked event occured on the window. The co-ordinates are relative to the upper left corner of the window.


tnGetWindowTitle(TN_WIDGET *window, char *title)

Returns : The currently set title of the window.


tnSetWindowTitle(TN_WIDGET *window, char *title)

Description : Sets the window title as specified.

5.2 TN_BUTTON

Introduction

This is the Push Button widget. It can be placed inside a window widget. The push button supports either a text caption or a pixmap as its face.

Specifications

By default a button has a caption which is set to "Button". The following properties can be specified optionally for a button while calling tnCreateWidget

Examples:

A button specification with pixmap file "/usr/share/pixmaps/foo.xpm"


mybutton=tnCreateWidget(TN_BUTTON,mywindow,10,10,TN_HEIGHT,50,TN_WIDTH,50,
                        TN_PIXMAP,TN_TRUE,
                        TN_FILENAME,"/usr/share/pixmaps/foo.xpm",
                        TN_END);
                        

A button with default values and a caption "TinyWidgets"



mybutton=tnCreateWidget(TN_BUTTON,mywindow,10,10,
                        TN_CAPTION,"TinyWidgets",
                        TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a button.

Utility Functions

The following utility functions can be used for a button to access and change its properties.


int tnGetButtonPressed(TN_WIDGET *widget)

Description: Get the button number for the last CLICKED event on the button.

Returns: A mask containing set bits for number of mouse buttons which were involved in the clicked event.


int tnSetButtonPixmap(TN_WIDGET *widget,char *filename)

Description: Sets pixmap for the face of a button.

Returns: 1 on success, -1 on failure.


int tnRemoveButtonPixmap(TN_WIDGET *widget)

Description: Removes a pixmap on the face of the button and sets empty caption.

Returns: 1 on success, -1 on failure.


int tnSetButtonCaption(TN_WIDGET *widget,char *caption)

Description: Sets a caption on the face of a button.

Returns: 1 on success, 0 if a pixmap already present on button, -1 on failure.


int tnGetButtonCaption(TN_WIDGET *widget,char *caption)

Description: Copies the caption of the button into the string pointed by caption

Returns: 1 on success, -1 on failure.


TN_HASPIXMAP(TN_WIDGET *widget)

Description: This is a macro that returns 1 if the face of the button is a pixmap , 0 otherwise.

Returns: 1 if face has a pixmap, 0 otherwise.

5.3 TN_LABEL

This is the static label widget. It provides the facility of adding static text labels to a window widget. The label supports various fonts,font sizes and colors. By default the label is black colored and automatically resizes itself according to the font size.

Specifications

By default a label has a caption which is set to "Label". The following properties can be specified optionally for a label while calling tnCreateWidget

Examples:

A label specification with foreground black,background white and caption "Hello World!"


mylabel=tnCreateWidget(TN_LABEL,mywindow,10,10,
                        TN_CAPTION,"Hello World!",
                        TN_BGCOLOR,TN_RGB(255,255,255),
                        TN_FGCOLOR,TN_RGB(0,0,0),
                        TN_END);
                        

A label with a caption "TinyWidgets",and with courier new font, size 16 points



mylabel=tnCreateWidget(TN_LABEL,mywindow,10,10,
                        TN_FONTNAME,"cour",
                        TN_FONTSIZE,16,
                        TN_CAPTION,"TinyWidgets",
                        TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a label.

Utility Functions

The following utility functions can be used for a label to access and change its properties.


int tnSetLabelCaption(TN_WIDGET *widget, char *caption)

Description: Sets the caption for a label to caption

Returns: 1 on success, -1 on failure.


int tnSetLabelCaptionColor(TN_WIDGET *widget, TN_COLOR color)

Description: Sets the color of the caption to color for the label

Returns: 1 on success, -1 on error.


TN_COLOR tnGetLabelCaptionColor(TN_WIDGET *widget)

Description: Gets the color of caption for the label

Returns: The color of caption on success , -1 on error.


int tnGetLabelCaption(TN_WIDGET *widget,char *caption)

Description: Gets the caption for the label.

Returns: 1 on success, -1 on failure.

5.4 TN_CHECKBUTTON

Introduction

This is the checkbutton widget. It can be placed inside a window widget. It is like a toggle button.

Specification

The following properties can be optionally set via the tnCreateWidget call:

Examples:

A checkbutton with a caption of "TinyWidgets", to be displayed in Courier Font and fontsize 8.


checkbtn0 = tnCreateWidget(TN_CHECKBUTTON,window0,35,45,TN_FONTNAME,"cour",TN_FONTSIZE,8,TN_CAPTION,"TinyWidgets",TN_END);

Callbacks

The following callbacks can be registered for a checkbutton via tnRegisterCallBack.

Utility Functions

The following utility functions have been provided to manipulate the checkbutton


int tnGetCheckButtonCaption(TN_WIDGET *checkbutton, char *caption)

Description : Returns the currently set caption of the checkbutton.


int tnSetCheckButtonCaption(TN_WIDGET *checkbutton, char *caption)

Description : Sets the caption of the checkbutton.


int tnSetCheckButtonStatus(TN_WIDGET *checkbutton, TN_BOOL status)

Description : Sets the status of the checkbutton as specified.


TN_CHECKBUTTONACTIVE(checkbutton)

Description : A macro which tests if the checkbutton is active.

5.5 TN_RADIOBUTTONGROUP

Introduction

This is the radio button group widget. It can be placed inside a window widget. A radio button group needs to be created for grouping radio buttons. All radio buttons in a group will behave in a mutually exclusive manner.

Specification

The default caption for a radio button group is "RadioButton Group". The following properties can be optionally set via the tnCreateWidget call:

Callbacks

The following callbacks can be registered via tnRegisterCallBack

Utility Functions


int tnSetRadioButtonGroupCaption(TN_WIDGET *widget,char *caption)

Description: Sets the radio button group caption text.

Returns: 1 on success. -1 on failure.


int tnGetRadioButtonGroupCaption(TN_WIDGET *widget,char *caption)

Description: Gets the radio button group caption.

Returns: 1 on success. -1 on failure.


int tnGetRadioButtonGroupClickedPos(TN_WIDGET *widget,int *x,int *y)

Description: Returns the x & y co-ordinates at which the pointer is clicked inside the radio button group.

Returns: 1 on success. -1 on failure.

5.6 TN_RADIOBUTTON

Introduction

This is the radio button widget. It is to be placed inside a radio button group widget.

Specification

The default caption for a radio button is "Radio Button". The following properties can be defined via the tnCreateWidget call

Utility Functions


int tnSetRadioButtonCaption(TN_WIDGET *widget,char *caption)

Description: Sets the caption text for the radio button.

Returns: 1 on success. -1 on failure.


int tnGetRadioButtonCaption(TN_WIDGET *widget,char *caption)

Description: Gets the radio button caption.

Returns: 1 on success. -1 on failure.


int tnSetRadioButtonStatus(TN_WIDGET *widget,TN_BOOL status)

Description: Sets the radio button status to selected (TN_TRUE) or unselected (TN_FALSE).

Returns: 1 on success. -1 on failure.

5.7 TN_TEXTBOX

Introduction

The current textbox implementation although is almost usable is still under development. The user is advised to use the textbox widget with care.

This is the textbox widget. The textbox provides an editable text box on a window. Currenltly TinyWidgets supports single line (text entry field) and multiline textboxes(text areas). The textbox uses many special keys and hence relies on the scancode driver of microwindows. It has NOT been tested on other keyboard drivers and we wish to state clearly that it may not work with them. By default the textbox is a single line textbox with no default text.

Specifications

The following properties can be specified optionally for a textbox while calling tnCreateWidget

Examples:

A single line textbox with font Times New Roman, size 16 points and default text set to "Hello World!"


mytextbox=tnCreateWidget(TN_TEXTBOX,mywindow,10,10,
                         TN_TEXTBOXTYPE,TN_SINGLE_LINE,
                         TN_DEFAULTTEXT,"Hello World!",
                         TN_FONTNAME,"times",
                         TN_FONTSIZE,16,
                         TN_END);

A simple multiline textbox with no default text.


mytextbox=tnCreateWidget(TN_TEXTBOX,mywindow,10,10,
                         TN_TEXTBOXTYPE,TN_MULTI_LINE,
                         TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a textbox.

Utility Functions

The following utility functions can be used for a textbox to access and change its properties.


char * tnGetText(TN_WIDGET *widget)

Description: Returns the text in a buffer contained in the textbox. The user has to free the returned buffer.

Returns: A pointer to a character buffer containing the characters in the textbox on success, NULL on error.


int tnSetText(TN_WIDGET *widget,char *text)

Description: Sets the text in the textbox to text

Returns: 1 on success. -1 on failure.

5.8 TN_SCROLLBAR

This is the scrollbar widget. These scrollbars can be placed on windows. The scrollbar widget has two orientations, namely TN_HORIZONTAL and TN_VERTICAL. By default the scrollbar is is a vertical scrollbar, with range set from 0 to 100 and linestep = 1 , pagestep = 5. The thumb can also be dragged to an arbitary position using the mouse.

Specifications

The following properties can be specified optionally for a scrollbar while calling tnCreateWidget

Example: A vertical scrollbar with range 50 to 100 and pagestep = 10 , linestep = 2


myscrollbar=tnCreateWidget(TN_SCROLLBAR,mywindow,10,10,
                           TN_ORIENTATION,TN_VERTICAL,
                           TN_MINVAL,50,
                           TN_MAXVAL,100,
                           TN_LINESTEP,2
                           TN_PAGESTEP,10,
                           TN_END);

A horizontal scrollbar with default properties

myscrollbar=tnCreateWidget(TN_SCROLLBAR,mywindow,10,10,
                           TN_ORIENTATION,TN_HORIZONTAL,
                           TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a scrollbar.

Utility functions


int tnGetScrollbarOrientation(TN_WIDGET *widget,int *orientation)

Description: Sets *orientation to either of TN_HORIZONTAL or TN_VERTICAL

Returns: 1 on success, -1 on error


int tnSetScrollbarOrientation(TN_WIDGET *widget,int orientation)

Description: Sets the orientation of scrollbar to orientation

Returns: 1 on success, -1 on error


int tnGetScrollRange(TN_WIDGET *widget,int *minval,int *maxval)

Description: Gets the range of scrollbar into *minval and *maxval

Returns: 1 on success, -1 on failure.


int tnSetScrollRange(TN_WIDGET *widget,int minval,int maxval)

Description: Sets the range of scrollbar from minval to maxval

Returns: 1 on success, -1 on failure.


int tnGetScrollStepSizes(TN_WIDGET *widget,int *pagestep,int *linestep)

Description: Gets the pagestep and linestep of scrollbar into *pagestep and *linestep respectively

Returns: 1 on success , -1 on failure.


int tnSetScrollStepSizes(TN_WIDGET *widget,int pagestep,int linestep)

Description: Sets the pagestep and linestep of scrollbar to pagestep and linestep respectively

Returns: 1 on success , -1 on failure.


int tnSetThumbPosition(TN_WIDGET *widget,int position)

Description: Sets the position of the thumb to position

Returns: 1 on success , -1 on failure.


int tnGetThumbPosition(TN_WIDGET *widget)

Description: Gets the position of the thumb

Returns: Thumb position on success , -1 on failure.


int tnGetLastScrollEvent(TN_WIDGET *scrollbar)

Description: Gets the last scrolling event that occured with the scrollbar.

Returns: On success returns one of

On failure returns -1

5.9 TN_PROGRESSBAR

Introduction

This is the progressbar widget. It can be placed inside a window widget.

Specifications

A progress bar can be of type :

A continous progressbar is created by default. The following properties can be optionally specified for a progressbar via the a call to tnCreateWidget

Utility functions


void tnProgressBarUpdate(TN_WIDGET *pbar, int value)

Description: Set the value for the progress bar. Returns: nothing


int tnGetProgressBarValue(TN_WIDGET *widget)

Description: Returns the current value for the progress bar.

Returns: The current value on success. -1 on failure.


int tnSetProgressBarFillColor(TN_WIDGET *widget,TN_COLOR color)

Description: Set the current fill color to "color".

Returns: 1 on success. -1 on failure.


TN_COLOR tnGetProgressBarFillColor(TN_WIDGET *widget)

Description: Returns the fill color.

Returns: The current fill color on success. -1 on failure.


int tnSetProgressBarStepSize(TN_WIDGET *widget,int stepsize)

Description: Sets the step size for a discrete progress bar.

Returns: 1 on success. -1 on failure; will return -1 for a continuous progress bar.


int tnGetProgressBarStepSize(TN_WIDGET *widget)

Description: Returns the current step size.

Returns: The current step size on success. -1 on failure ; will return -1 for a continuous progress bar.

5.10 TN_LISTBOX

Introduction

This is a listbox widget which allows the user to display a list of items on the screen.

Specifications

The following optional properties can be specified while calling tnCreateWidget.

Examples:

A listbox specification with default properties and 5 Items to be displayed.


 
char *s[] = {"Monday","Tuesday","Wednesday","Thursday","Friday"};
listbox1 = tnCreateWidget(TN_LISTBOX,window1,10,20,TN_COUNT,5,TN_LISTITEMS,s,TN_END);

An empty Listbox with Times Font to be used to display the List Items.


listbox2 = tnCreateWidget(TN_LISTBOX,window1,20,30,TN_FONTNAME,"times",TN_FONTSIZE,12,TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a listbox.

Utility Functions

The following utility functions have been provided for manipulating the listbox.


int tnGetSelectedListItems(TN_WIDGET *widget, char ***listitems,int *count)

Description : Allocates space and returns the selected items in the listbox(multiple items can be selected using the Cntrl key modifier). Count contains the number of selected items. The user is expected to free the Listitems after he has finished using them.


int tnGetAllListItems(TN_WIDGET *listbox, char ***items, int *count)

Description : Returns all the items in the Listbox. The user is again expected to free the list of items.


int tnGetSelectedListNum(TN_WIDGET *listbox)

Returns: The number of items selected in the Listbox, -1 if there is an error.


int tnGetSelectedListPos(TN_WIDGET *listbox,int **pos,int *count)

Description : Returns the indices of the selected list items and their count. The pos array is allocated in the function and hence the user must free it after he is finished.


int tnGetListItemPos(TN_WIDGET *listbox, char *item)

Description : Given an item, it returns its index in the Listbox.

Returns : -1 if the item was not found in the Listbox, or some error occured.


int tnAddItemToListBox(TN_WIDGET *listbox, char *item)

Description : Adds the item to the end of the list of items currently in the Listbox.


int tnAddItemToListBoxAt(TN_WIDGET *listbox, char *item, int pos)

Description : Adds the item to the list of items currently in the Listbox at the position specified by pos. If pos is greater than the number of items currently in the listbox then the item is added to the end of the list of items.


int tnDeleteItemFromListBox(TN_WIDGET *listbox, char *item)

Description : Deletes the item from the list of items currently displayed in the listbox.

Returns: -1 if the item was not found in the Listbox.


int tnDeleteItemFromListBoxAt(TN_WIDGET *listbox, int pos)

Description : Deletes the item from the Listbox whose index is specified by pos.

Returns: -1 if pos is greater than the number of items in the listbox.


int tnDeleteSelectedItems(TN_WIDGET *listbox)

Description : Deletes all the items in the listbox which have been selected by the user.


int tnDeleteAllItemsFromListBox(TN_WIDGET *listbox)

Description : Deletes all the items from the Listbox.


int tnSetSelectedListItem(TN_WIDGET *listbox,char *item, TN_BOOL selected)

Description : Sets the status of the item in the listbox as specified by the selected parameter (TN_TRUE = selected, TN_FALSE = unselected).

Returns : -1 if the item is not found in the Listbox.


int tnSetSelectedListItemAt(TN_WIDGET *listbox, int pos, TN_BOOL selected)

Description : Sets the status to selected, of the item whose index is specified by pos.

Returns : -1 if the index is specified is greater than the number of items in the listbox.


int tnListItemsLineUp(TN_WIDGET *widget, int number)

Description : Scrolls the list of items displayed in the listbox up by the number of lines specified. Work only if the TN_RESIZE property of the listbox is set to TN_FALSE.


int tnListItemsLineDown(TN_WIDGET *widget, int number)

Description : Scrolls the list of items displayed in the listbox up by the number of lines specified. Works only if the TN_RESIZE property of the listbox is set to TN_FALSE.


int tnGetListTop(TN_WIDGET *listbox)

Description : Gets the index of the item displayed at the top of the Listbox. Works only if the TN_RESIZE property of the listbox is set to TN_FALSE. The above three functions can be used in conjunction with the scrollbar to scroll the items displayed in the Listbox.


int tnGetListBoxResize(TN_WIDGET *listbox, TN_BOOL *resize)

Description : Returns the currently set resize property of the listbox


int tnSetListBoxResize(TN_WIDGET *listbox, TN_BOOL resize)

Description : Sets the resize property of the listbox as sepcified.

5.11 TN_PICTURE

Introduction

This is the picture widget and allows the user to display images(BMP, JPEG, GIF etc) in a picture container.

Specifications

The following optional properties can be specified for a picture while calling tnCreateWidget

Examples:

A picture specification with the image file "/root/Images/liz.jpg" where the container is resized to the size of the image.


mypicture=tnCreateWidget(TN_PICTURE,window0,50,50,TN_FILENAME,"/root/Images/liz.jpg",TN_STRETCH,TN_TRUE,TN_END);

Callbacks

The following callbacks can be specified while calling tnRegisterCallBack for a Picture.

Utility Functions

The following utility functions have been provided for the Picture widget to access and change its properties.


 int tnGetPictureProps(TN_WIDGET *picture, TN_BOOL *stretch, char **filename) 

Description: This function returns the currently set properties of the picture i.e. Stretch and the filename of the currently displayed image in the picture. The user is expected to free the filename string which this function allocates.

Returns: 1 on success, -1 on failure.


 int tnSetPicture(TN_WIDGET *picture, char *filename) 

Description: This function loads the image specified by filename into the picture widget.

Returns: 1 if succesful, -1 in case of error.


 int tnSetPictureStretch(TN_WIDGET *picture,GR_BOOL stretch) 

Description: This function sets the Stretch property of the picture widget.


 int tnPictureDup(TN_WIDGET *destpic,TN_WIDGET *srcpic) 

Description: 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.


 int tnGetPictureImageProps(TN_WIDGET *picture, TN_IMAGE_INFO *iinfo) 

Description: Fills the iinfo structure with the following properties relevant to the image displayed in the picture container.

5.12 TN_MENUBAR

Introduction

This is the menu bar widget. It is to be placed in a window widget.

Specification

A call to tnCreateWidget will create a horizontal menu bar, which is aligned to the window top and resized to the window width, by default. The x & y position can optionally be specified.

Examples: The following call will create a default menu bar (aligned to the window top)


menu_bar = tnCreateWidget(TN_MENUBAR,window,0,0,TN_END);

5.13 TN_POPUPMENU

Introduction

This is the popup menu widget. It allows for creation of popup menus. It is to be placed inside a menubar widget. A popup menu widget must be defined for providing pull down menu functionality.

Specification

The following properties can be set via the tnCreateWidget call

Examples: The following call will create a default popup menu with the label "File". (The TN_AUTO keyword indicates that positioning will be automatically handled).

popup_menu = tnCreateWidget(TN_POPUPMENU,menu_bar,TN_AUTO,TN_AUTO,TN_CAPTION,"File",TN_END);

5.14 TN_CASCADEDMENU

Introduction

This is the cascade menu widget. It is to be placed inside a popup menu widget. It provides cascade (horizontal menus) functionality. A cascade menu will be displayed as a label with a rightward pointing arrow.

Specification

The following properties can be set via the tnCreateWidget call

Examples: The following call will create a default cascade menu atached to a popup menu, with the label "Tools". (The TN_AUTO keyword indicates that positioning will be automatically handled).

cascade_menu = tnCreateWidget(TN_CASCADEMENU,popup_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Tools",TN_END);

5.15 TN_MENUITEM

Introduction

This is the menu item widget. It can be placed inside any of the following

It is the basic menu item which when clicked, a programmer defined action can be taken.

Specification

The following properties may be set via the tnCreateWidget call

Examples: The following call will create a basic menu item with the label "Open", within a popup menu. (TN_AUTO for the x & y positions indicates automatic positioning).

mitem0 = tnCreateWidget(TN_MENUITEM,popup_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Open",TN_END);

The following call will create a checkable (toggle) menu item within a cascade menu.


mitem1 = tnCreateWidget(TN_MENUITEM,cascade_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Tool1",TN_CHECKABLE,TN_TRUE,TN_END);

Callbacks

The following callback(s) can be registered via the tnRegisterCallBack call


Next Previous Contents