Pwrap Widgets

From OpenAlchemy.org

In this section we list the widgets provided by Pwrap. The sequel provides Pwrap sample programs to illustrate typical usages of these widgets in applications.

Contents 1 Frame 2 Toplevel 3 Label 4 Button 5 Entry 6 Radiobutton 7 Checkbutton 8 Listbox 9 Widget Listbox (Wlistbox) 10 Text Listbox (Tlistbox) 11 Combobox 12 Progress Bar 13 Tab Frames 14 Text Box 15 Sketch 16 Scrollbar 17 Slider 18 Dialog Boxes 19 Graphics 20 Messagebox 21 Timer

Frame

A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. A frame can be created using the following API,

pw_widget pw_create_frame(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

When a frame is created it has no default event bindings. Frames are not meant to be interactive. By default the only action a frame performs on receiving an event is to redirect it to the appropriate child.

Toplevel

A toplevel is a container for other widgets. A toplevel window can be created using the following API,

pw_widget pw_create_window(unsigned width, unsigned height, ...);

Unlike a frame, a toplevel creates a new window on the screen. Every widget, other than toplevel windows, in your application/program should be a descendant of some toplevel. Several events such as window configure, up button, exit, etc are bound to a toplevel window.

Label

A label is a widget that displays a textual string in a single font. The text can span multiple lines, if the text contains newlines. A label has no default bindings. It is not meant to be interactive. A label can be created using the following API,

pw_widget pw_create_label(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

In order to change the look (i.e. font color, size and type) and the text/message in a label widget, APIs are available to achieve this.

Button

The concept of a button is rudimentary to any user interface (UI) and widget set, and it is no different for Amida applications and Pwrap. A button can be created using the following API,

pw_widget pw_create_button(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);}

The Pwrap button widget can display text or image. Buttons can be created and they can be associated with events. They can be set to different states such as normal, active or disabled. The default bindings are:

• On ButtonPress the state of the widget is changed to active and re-rendered.
• On ButtonRelease the state of the widget is changed to normal and re-rendered.

Entry

The Entry is a basic input widget that allows text to be typed and displayed in a single line text box. An entry widget can be created using the following API,

pw_widget pw_create_entry(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

There would be applications that require the text inputted by the user not to be made visible. For instance, when asking a user to type her/his password, it is generally advisable that the typed password is not made visible. This is facilitated by the following API,

void pw_entry_passwdchar(pw_widget widget, char ch);

This API will replace the actual text entry with some special character given. Apart from this, the entry widget has all the other standard APIs for clearing the text, getting the value of the inputted text, setting the text in the entry, etc. Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands may be used to change the view in the window.

Radiobutton

A radiobutton is a widget that displays a textual string or an image with an indicator button (that appears as a circle). If there is text to be displayed, it can appear in a single font, but it may span several lines (if the text contains newlines). A radiobutton can be created using the following API,

pw_widget pw_create_radiobutton(pw_widget parent, int x, int y, unsigned width, unsigned height, pw_widget group, ...);

A radiobutton behaves like a simple button: it can display itself in either of three different ways, according to the state option.

Radiobuttons are typically used when a single choice out of a small number of choices needs to be selected. These small number of choices need to be grouped together. APIs are available to allow for grouping of radiobuttons, to know the status of a radiobutton and to select/deselect a radiobutton.

Checkbutton

Checkbuttons are very similar to radiobuttons, except that they are not grouped together. Rather than being text/image with a circular indicator button,checkbuttons have indicator buttons as squares with the text/image appended to them. These are typically used when one or more choices from among a small number of choices need to be turned on or off. A checkbutton can be created, using the following API,

pw_widget pw_create_checkbutton(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

APIs are available to select/deselect and to know the status of a checkbutton.

Listbox

In most widget sets, creating a listbox involves creating a window with a scrollbar, adding frames to it and then placing the required widgets. This process becomes cumbersome if all that the developer wanted was to display text. Achieving this using widgets becomes expensive in terms of time and memory. As such Pwrap provides two types of listboxes,

• Widget Listbox
• Text Listbox

Widget Listbox (Wlistbox)

It is like any other listbox. It is a widget which contains other widgets. It provides scrollbar if the widget inserted exceeds the height of the toplevel. A Wlistbox can be created using the following API,

pw_widget pw_create_wlistbox(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);}

Wlistbox provides APIs for inserting a widget at the end of the list or at a specified index, to clear the listbox, to see the widget at a given index, etc.

Text Listbox (Tlistbox)

A Text listbox is useful when we know for sure that the listbox will contain only rows of text. We can directly insert the text in a row into Tlistbox without using an additional widget. A Tlistbox can be created using the following API,

pw_widget pw_create_tlistbox(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);}

The Text listbox provides all the APIs provided by the Wlistbox. In addition, it provides APIs to count the number of rows, to get the text in a particular row, to select/deselect any set of rows, etc. A Text listbox can be in either single selection mode or multiple selection mode. In the latter mode, the user can select a multiple set of rows.

Additionally, the Text Listbox has the capability to have more than one column. That is, if the data to be displayed needs to be shown in two or more columns, then the following API would be necessary,

pw_widget pw_tlistbox_addcolumn(pw_widget widget, unsigned width);

When inserting row data into a multi-column text listbox, it is necessary to specify the column to which the data needs to be inserted.

Combobox

A Combobox is a dropdown text listbox that allows for a single option to be selected from a variable number of options. Radiobuttons and text listboxes occupy screen space and as such, the Combobox is a utility widget that saveson screen space when a single item needs to be selected from a (variable) number of items. A Combobox can be created using the following API,

pw_widget pw_create_combobox(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

The Combobox provides APIs to insert/remove options, to get/set the current selected option, to be intimated when there is change in the selection, etc.

Progress Bar

Progress bars are useful for showing the progress/status of an operation. The progress/status of the operation can be specified by incrementing (decrementing) the status from 0 to 100 (from 100 to 0). A Progress Bar can be created using the following API,

pw_widget pw_create_progressbar(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

APIs for setting the value of the progress, setting the colour, getting the value, etc. are available. The example progress bar in the Pwrap samples directory provides further details.

Tab Frames

Tab frames are frames overlapped over each other. It has a tag name at the top and can be brought into display when the tag name is pressed. To create a tabbed frame, use the following API,

pw_widget pw_create_tab(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

pw_widget pw_tab_add_page(pw_widget widget, const char *title, Bool(*tab_callback)(pw_widget, pw_event));

Using the first API, the tab frame is created. To add another frame to the tab, the second API is used. Apart from this, APIs are available to raise a frame to the top, get the active page etc. For further reference, refer to the example, tab example in the Pwrap samples directory.

Text Box

Text box is similar to entry widget, except that the text box can have multiple lines with a vertical scroll bar. To create a text box, use the following API,

pw_widget pw_create_textbox(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

We can load a text file, save the contents into a file, count the number of lines etc. Refer to the example, tab example in the Pwrap samples directory.

Sketch

The Sketch widget provides a window for freehand writing/drawing on the Amida. Antialiasing is incorporated into the behaviour of the widget. A freehanddrawing area can be created using the following API,

pw_widget pw_create_sketch(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

A default pen is associated with every sketch widget. The width and color ofthe pen can be separately set. There are APIs to save the sketch to a file or buffer and to load a saved sketch from a file or buffer. It is possible toclear the writing/drawing on a sketch widget. The example tab example in thePwrap samples directory contains a sample usage of a sketch widget.

Note that, the redraw event is taken care of internally. So there is no need to worry about the exposure event. The sketch will remain intact even when you hide the widget, unless you clear the contents or destroy the widget explicitly.

Scrollbar

A Scrollbar in Pwrap is like any other scrollbar. There are vertical and horizontal scrollbars. The APIs for creating scrollbars is as follows,

vertical scrollbar: pw_widget pw_create_vscrollbar(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

horizontal scrollbar: pw_widget pw_create_hscrollbar(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

There are APIs to set/get the scrollbar¿s slider position, to set the lengthand increment of the scrollbar¿s slider as per the developer¿s requirement. It is possible to be intimated, via an event handler, whenever there is a change in the scrollbar's slider position.

Slider

Slider widgets are typically used for scales (i.e. to visually select a value within a range). Sliders also come in two flavours - vertical and horizontal. It is the horizontal slider which is mostly preferred. Slider widget canbe created using the following APIs,

vertical sliders: pw_widget pw_create_vslider(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

horizontal sliders: pw_widget pw_create_hslider(pw_widget parent, int x, int y, unsigned width, unsigned height, ...);

APIs are available to set the slider range and position. APIs are also available to handle the slider motion with a callback function. We can also get the value of the current slider position.

Dialog Boxes

A dialog box is a simple window with certain things packed into it. To create a dialog box, use the following API,

pw_widget pw_create_dialog(unsigned width, unsigned height, ...);

To set a child for the dialog box, use the following API,

pw_widget pw_create_child_dialog(pw_widget parent, unsigned width, unsigned height, ...);

Dialog box can interact with the user, in terms of an action for every event. To know more about it, refer to the example, dialog box in the Pwrap samples directory.

Graphics

Pwrap provides certain basic graphical widgets like point, line, rectangle, circle and arc. The graphical APIs are,

For point,

void pw_draw_point(pw_widget widget, int x, int y);

For line,

void pw_draw_line(pw_widget widget, int x1, int y1, int x2, int y2);

For rectangle,

void pw_draw_rectangle(pw_widget widget, int x, int y, int width, int height);

For rectangle with colour filled,

void pw_fill_rectangle(pw_widget widget, int x, int y, int width, int height);

For circle,

void pw_draw_circle(pw_widget widget, int x, int y, int radius);

For arc,

void pw_draw_arc(pw_widget widget, int x, int y, int a, int b, int start_angle, int end_angle);

For arc with colour filled,

void pw_fill_arc(pw_widget widget, int x, int y, int a, int b, int start_angle, int end_angle);

For choosing colour,

void pw_set_drawcolor(const char *color);

Refer to the example, graphics_demo, to know more about it.

Messagebox

This will give a messagebox in terms of an information or warning or an error depending upon the program. The API to create a messagebox is,

messagebox_button pw_messagebox(pw_widget toplevel, messagebox_buttontype, messagebox_icon icon, const char *title, const char *mesg);

It has to created only over the toplevel. The 2^nd parameter messagebox button type can be any one of the following,

• MSGTYPE YESNO,
• MSGTYPE YESNOCANCEL,
• MSGTYPE OK,
• MSGTYPE OKCANCEL,
• MSGTYPE RETRYCANCEL,
• MSGTYPE ABORTRETRYCANCEL,
• MSGTYPE CUSTOM,
• MSGTYPE NOTYPE

The 3^rd parameter meassagebox icon icon can be any one of the following,

• MSGICON ERROR,
• MSGICON INFO,
• MSGICON QUESTION,
• MSGICON WARNING,
• MSGICON NOICON

Timer

Timer is like any other timer control. It gives timing control to time any operation. The API to create a timer is,

pw_timer pw_create_timer(unsigned long time, int repeat, Bool(*callback)(void*, void*), void *arg1, void *arg2);

The repeat option can be True or False. If it is true, the callback functionwill be repeatedly called after the interval time specified in the first parameter gets over. If it is False, it will be called only once after the interval time. Timers can also be destroyed. Refer to the example, timer demo, in the Pwrap samples directory to know more about timers.