HYDRASUB GUI, A C++ wrapper library for Motif

HYDRASUB GUI,HYDRASUB GUI,A C++ wrapper A C++ wrapper library for Motif.library for Motif.

Introduction

The Hydrasub library was developed by Bård Grønbech at the Hydrological Data section at the Norwegian Water Resources and Energy Administration in 1995-1997. The code was further developed by Trond Reitan from 1998 and up to now.It is a set of wrapper classes and methods for building graphics interface programs using Motif (or Lesstif). Hydrasub has classes for menus, lists and buttons, among other graphic components. This documentation handles the GUI part of the Hydrasub library. In addition, the Hydrasub library carries a few basic items (like handling date-times.)

Why Hydrasub?

One test of the simplicity of a language or library is the size and complexity of a ”Hello World” program. That’s a program that only shows the text ”Hello World”. In perl and shell, this can be done with two separate program lines. Using C, you need a couple of lines extra. So far, we’ve only discussed non-graphic ”Hello World” programs, though. The question is; how large does a graphic program need to be? The ”Hello World” example program I saw in Visual C++, was awfully large and complex. (Much of the code was automatically inserted,

and was not object oriented at all.) The C interface for X/Motif was a bit simpler, but the programmer still needed to fill a large page of relatively obscure code to get the ”work” done. Java is much better. You need only about ten to fifteen lines, in order to make the ”Hello World” program. Though it’s not intuitive that the program has to look the way it does, the code is relatively readable. The main quibble people have with Java is that it’s slow, has poor string routines and seems to eat more system resources than is needed for the job.

Using Hydrasub

The great thing about Hydrasub is that it has an interface thatlooks quite a bit like the way one Java accesses the graphic components (Java 1.0). There aren’t as many different graphic components in this library, but I found most that have needed. As in Java, on first makes container widgets and then builds the other widgets into these ones, by specifying that the containers should be the ’parent’ widgets.

As in Java (1.0), one subscribes to user events by (re-)defining how certain methods belonging to a widget should work. These methods are virtual (though they are implemented in the original classes), and have names such as ’pushed’ or ’OneHit’. All virtual methods in this library are ways in which a programmer can access user events belonging to a given class.

Hydrasub Hydrasub introductionintroduction

The widget class is a C++ wrapper for ’Widget’, the Motif structure for general graphic components (’widgets’). All classes (except ’mainwin’) in Hydrasub are subclasses of the widget class. Thus it has no appearance in itself, but defines a set of methods that are common to all it’s subclasses. Here are the most important of these methods;

int IsMapped(void) - Returns 1 if the widget is ’mapped’, that is, made visible. void Map(void) - If the widget isn’t visible, this command will make it so. Note; most widgets are made visible when they’re built. The main exception is the ’shell’ class, that represent sub-windows.

void Unmap(void) - Removes the widget from the screen.

void Width(Dimension width) - Sets the width of the widget.

void Height(Dimension height) - Sets the height..

Dimension Width(void) - Returns the width of the widget.

Dimension Height(void) - Returns the height.

The widget class

More about the widget class

void Background(char *color) - Sets the background colour of the widget by specifying the widget background colour as a string. (For legal names, see the program colorview.)

void Foreground(char *color) - Sets the foreground colour of the widget.

void Beep(int sec) - Does just that... :)

int screenwidth(void) - Returns the screen width in the window where the widget is found.

int screenheight(void) - Returns the screen height.

Routines used in conjugation with the widget class

void AddWorkCursor(widget w) - Uses a ’clock’ mouse cursor over the given widget (usually a window). (Note; it is still possible to use widgets under the marker, unless you use the InSensitive method. This method only transforms the cursor.)

void RmWorkCursor(widget w) - Reinstalls the normal mouse cursor in the widget and it’s sub-widgets.

void Sensitive(void)/InSensitive(void) - Makes the widget sensitive/insensitive to user input. The widget is sensitive as default.

The class for the main window - ’mainwin’

The mainwin class represents the main window of an application. It has a constructor that reflects this, by taking the program arguments as input strings. Typically, one object of this class is made in the main-loop of the program, after which the Run method of this class is called. (Often this is all that’s found in the main-loop.)

Important methods:

mainwin(char *title, int argc, char **argv) - The constructor of mainwin takes the argument count and the arguments from the main loop as input. Usually the contents of the main window is built in the constructor of the main window class, which has to be a subclass of this class.

Run(void) - This method ”Runs” the program. What this means is that the program will set up and show all the components and wait for input from the user.

void Iconify(void)/DeIconofy(void) - Iconifies (or deiconifies) the main window.

Example using mainwin:

Here we’ll show a simple program that uses the mainwin class in order to make a ”Hello World” program. The class label will also be used, in order to make the text that’s to be shown in the main window. (The label class will be explained shortly.)

Note that we’ll do it the hard way in this program, by defining a subclass of mainwin and it’s constructor. The constructor then builds it’s sub-widgets. For the purpose of this program, one could make a few shortcuts...motifhello.C:

#include "motifhello.H"

hello::hello(char *title,int argc,char **argv) : mainwin(title,argc,argv){ hellabel.build(*this,"Hello!"); // builds the label that says ’hello’}

main(int argc,char **argv){ hello h("hello-applic",argc,argv); // Calls the constructor which // sets up the window

h.Run(); // Lets the application run}

Example using mainwin (2):

motifhello.H:

The Result;

#include <mainwin.H>#include <label.H>

class hello : public mainwin{ label hellabel; // A label that presents the text in the window public

hello(char *,int,char **); // the constructor};

The label widget:

We have already seen a program that uses a subclass of the widget class, namely the label class. This may be the simples of widgets, as it’s sole purpose is to show a text in a window or a ’container’ (more about containers later).

The constructor of this class takes no input. However, if it’s to be shown, one needs to use the ’build’ method. The method name ’build’ is used in most of the subclasses of widget, in order to make a widget appear. Different widgets require different input in order to be made, so the input to the ’build’ method may vary from class to class. Normally the parent widget is the first argument in the method.

Important methods;

void build(Widget parent, char *title) - Puts the widget inside the parent widget ’parent’ and puts the text ’title’ inside it.

void labelString(char *fmt, …) - Changes the text that the widget displays. Takes the same kind of input as the printf routine. Appearance:

The ’row’ widget, anexample of a ’container’

If you need to have more that one widget (usually you do) inside a window, you have to put them inside a ’container’. A container is a widget where you can put several widgets inside it. The container which is (most) used in the Hydrasub library is called ’row’. The row class is virtual and has two subclasses, vrow and hrow. In a vrow widget the sub-widgets are placed vertically down from the top of the widget. In hrow the widgets are places from left to right.

Example showing buttons in a hrow:

Example showing buttons in a vrow;

More about the ’row’

class

As all other widgets, row has a build method that builds the widget. This method and other methods belonging to the class is shown here;

void build(Widget parent) - Builds the container (either as a hrow or as a vrow), where other components can be built inside it. (For instance, a hrow can be placed inside a vrow, or vice versa.)

void alignBeginning(void) - This is the default setting of the row widget. The sub-widgets are placed from the upper left-hand corner.

void alignCenter(void) -.Starts by putting widgets in the centre of the container.

void alignEnd(void) -.Starts by putting widgets in the lower right-hand corner.

void spacing(int pixels) - Puts some ’air’ in between widgets placed inside this container.

PS:For an example of program code using the row class, se shelluse.C/H and pushbuse.C/H.

Sub-windows, the ’shell’ and

’shelldialog’ classes

The ’shell’ and ’shelldialog’ classes can be used to make sub-windows of the main window. When making these objects, one usually puts a container inside it and then place the components of the window inside this container.

The ’shell’ class has several methods attached to it, among those a ’build’ method. One calls this method by specifying the window where this sub-window will be placed over (normally the main window, mainwin::toplevel). After having made the window, one usually calls the Map method from the widget class, in order to make the window visible. One can also make the window at the start of the program and make it appear by using the Map window whenever the situation calls for this.

More about the ’shell’ and

’shelldialog’ classes

Methods in shell/shelldialog:

void build(Widget parent, char *title) - Makes a window placed above the parent window and containing the title ’title’.

void Iconify(void) - Iconifies the window

void DeIconify(void) -De-Iconifies the window.

Special for shell:

void Noborder(void) - No border around the window.

In conjugation with sub-window, two button classes has been made, namely closeshelldialog and closeshell. Objects of these classes are connected to a shelldialog or shell window, and when pushed the windows will be unmapped.

Making and using sub-windows (shell and shelldialog):

#include "shelluse.H"

shelluse::shelluse(char *title,int argc,char **argv) : mainwin(title,argc, argv){ hellabel.build(*this,”Nothing here..."); // contents of the main window helloshell.build(mainwin::toplevel,"Hello-shell"); // builds the shell shellrow.build(helloshell); // Makes a container shellabel.build(shellrow,"Hello!"); // label, as in 1st ex // pushbutton for closing the shell closeb.build(shellrow,&helloshell,”Close the window"); closeb.Background("red"); // set the background colour closeb.Foreground("white"); // set the foreground colour

helloshell.Map(); // show the shell window}

main(int argc,char **argv){ shelluse h("hello-applic",argc,argv); // run the constructor h.Run(); // run the ’application’}

Here is a program that shows how to use the shell and closeshell classes.

shelluse.C;

The Result;

If one pushes the ’close the window’ button, the window is closed.

#include <mainwin.H>#include <label.H>#include <shell.H>#include <row.H>

class shelluse : public mainwin{ label hellabel; // the label in the main window shell helloshell; // the subwindow vrow shellrow; // container closeshell closeb; // pushbutton for closing // the sub-window

label shellabel; // the label of the subwindowpublic: shelluse(char *,int,char **); // the constructor of // the main window};

Making and using sub-windows (shell and shelldialog) -2

shelluse.H;

closeshell and closeshelldialog

The closeshell and closeshelldialog are pushbuttons that closes a sub-window, either of the type shell or the type shelldialog. They are made by calling their ’build’ methods, where one specifies where the button is to be placed, a pointer to the window which is to be unmapped when the button is pushed and the button text.

Methods:void build(Widget parent, shell *pointer, char *title) - Makes a pushbutton with the title ’title’ and the parent widget ’parent’. The window pointed to by ’pointer’ will be closed when the button is pushed.

Se ”shelluse” for an example of how the class is used...

Dialog-windows:

The dialog class is a generic class for handling small ”dialog” window. These are used for giving the user small messages in a popup window. The window has a message and a ’close window’ button. By calling the ”ok_or_cancel” method, one can make two buttons appear.

These small windows are built (using the ’build’ method) almost like the shell windows, but are not meant to contain any other widgets. They do not require separate mapping, like the shell windows do.

Important methods;:void build(Widget parent, char *title, char *message) - Makes and maps the dialog window with the title ’title’ and the message ’message’.

int ok_or_cancel(char *okstr,char *cancelstr) - Activates the second button in the window and waits for the user to push one of them. Returns one if the user pushed the confirming button and zero if the user pushed the denying button.(labelled ’cancelstr’.

Appearance

The dialog class has a number of sub-classes, that are labelled accordingto their intended use; MessageDialog, ErrorDialog, InformationDialog, QuestionDialog, WarningDialog and WorkingDialog

Text fields - ’textf’

Text fields are used for fetching user input in the form of a text (string). They are usually editable but need not be. They have a label in front of them and a specified length. The textf class has a few subclasses, representing number fields (onlydigit), DateTime (more about the DateTime class later) fields (onlydatetime) and password fields. The textf class use purely virtual. A real component belonging to textf must either be a vtextf (vertical text field, the label comes over the field itself) or htextf, horizontal text field. The onlydigit and onlydatetime classes have similar subclasses.

Some of the methods; void build(Widget parent, char *title) - Makes a text field in the component ’parent’ with the label ’title’.

void build(Widget parent, int len, char *title) - As above, but enables the programmer to specify the field length.

void Editable(Boolean b) - Sets whether the field should be editable or not.

void SetText(char *text) - Sets the contents of the field

char *operator()() - Fetches the contents of the field.. Use: field.build(parent,”title”); char *contents=field();

void Clear (void) - Clears the field.

The appearance of the text field -

textf

Example of a horizontal text field htextf:

textfuse.C:

textfuse.H:

#include "textfuse.H"

textfuse::textfuse(char *title,int argc,char **argv) : mainwin(title,argc,argv){ inputf.build(*this,10,”Write something here:");}

main(int argc,char **argv){ textfuse t("hello-applic",argc,argv); t.Run();}

#include <mainwin.H>#include <textf.H>

class textfuse : public mainwin{ htextf inputf;public: textfuse(char *,int,char **);};

For a more interesting example, see pushbuse.C/H.

Larger text fields -the ’text’ class

It is also possible to have text fields that stretches over more than one line. To make such a widget, one can use the ’text’ class. The ’build’ method of this widget tells how large the field should be. Except for that, it is used much like the textf class.

Methods:

void build(Widget parent, int col, int row, Boolean edit) - Makes a text field with ’col’ columns and ’row’ rows in the parent component ’parent’. One can set whether the field should be editable or not, by using the ’edit’ variable. (Default; edit=True).

text &operator+=(char *) - This operator appends a given string to the text field. Example; text_object += ”This is an example”;

void Prepend(char *str) - Puts the string ’str’ in front of the contents of the text field.

void SetText(char *str) - Sets the contents of the field.

char *GetText(void) - Fetches the contents of the field.

void Clear(void) - Clears the field.

Appearance:For use, see the example belonging to the ’filesel’ class.

Buttons -’pushb’

Push-buttons are used for letting the user tell that an action is to take place. The ’pushb’ class has a ’build’ method that sets the label of the string. When the user pushes a button, the ’pushed’ method for that pushb object is called One can subscribe to button events by redefining the contents of the ’pushed’ method. This can be done by making a subclass of pushb where the ’pushed’ method is redefined. Usually, the a button object can’t do much on it’s own, and needs to tell the parent class (representing, for instance the window that uses the button) that the button has been pushed. This is often done by storing a pointer back to this larger class, when making the button. It is often smart to store the button type, too, so that one doesn’t need to define one subclass of pushb for each button one plans to use in the program.

Important methods;

void build(Widget parent, char *text) - Makes a push button in the component ’parent’ and with the text ’text’ written on the button.

virtual void pushed(void) - This method is call each time the button is pushed by the user.

This is the appearance of the ”pushbuse” program, that will be listed in the next pages.

Appearance of ’pushb’ objects

#include "pushbuse.H"

// CREATE -Should build a push button and store the necessary info// on the button type and the parent object pointer. void pushbuse_pushb::Create(widget parent, char *name, pushbuse *ipt,

BUTTON_TYPE type){ typ=type; // stores the button type (OK or EXIT) pt=ipt; // stores a pointer back to the main object build(parent,name); // builds the button}

// PUSHED - Called when the button is pushed. Notifies the main object // sending along the button type. void pushbuse_pushb::pushed(void){ pt->buttonpushed(typ); // Tells the main object that the button has // been pushed}

pushbuse.C:

A program example that uses the pushb

class;

pushbuse.C:

Continued on the next page;

// EXITQUEST - The ’quit’ button has been pushed...void pushbuse::exitquest(void){ // Make a dialog window that asks the user if he/she really wants to quit quest.build(mainwin::toplevel,”Question:",

”Do you really want to quit?"); // wait for an answer... if(quest.ok_or_cancel(”Yes","No")) exit(0); // A confirming answer means that we’ll quit}

// SENDTEXT - The button labelled ’fetch text’ has been pushed. Send the// text from the text field to a message dialog window. void pushbuse::sendtext(void){ char str[200]; // We’ll store the message string here sprintf(str,”Inside the text field is the following text found:\n\"%s\"",inputf()); // 'input()' fetches the text from the text field ”input”

// Build the dialog window; mess.build(mainwin::toplevel,"Message:",str);}

// BUTTONPUSHED - A button has been pushed. Take action // according to the button type; void pushbuse::buttonpushed(BUTTON_TYPE type){ switch(type) // Take action according to the button type.... { case PUSHB_OK: // ’fetch text' has been pushed sendtext(); // starts the 'sendtext’ method break; case PUSHB_EXIT: // ’quit’ has been pushed exitquest(); // start ’the exitquest’ method break; }}

Program example for the pushb class,

continued;

pushbuse.C:

// CONSTRUCTOR - Makes the main windowpushbuse::pushbuse(char *title,int argc,char **argv) : mainwin(title,argc,argv){ v1.build(*this); // Make the main container inputf.build(v1,10,”Write something here:"); // Make the input text field h1.build(v1); // Make a horizontal container

exitb.Create(h1,”Quit",this,PUSHB_EXIT); // Makes the ’quit’ button exitb.Background("red"); // Set the background colour red exitb.Foreground("white"); // ... and the foreground white

okb.Create(h1,”Fetch text",this,PUSHB_OK); // Makes the ’fetch text’ button okb.Background("green"); // Green background okb.Foreground("black"); // Black foreground}

// MAIN - the main loopmain(int argc,char **argv){ pushbuse pu("pushb-applic",argc,argv); // makes the main window pu.Run(); // runs the application}

pushbuse.H

#include <mainwin.H>#include <textf.H>#include <dialog.H>#include <pushb.H>#include <row.H>#include <stdlib.h>#include <unistd.h>

class pushbuse; // tell that the main class exists

enum BUTTON_TYPE {PUSHB_OK, PUSHB_EXIT}; // button types

// PUSHBUSE_PUSHB - A subclass of 'pushb' that ’talks to’ the main object when// the button is pushed; class pushbuse_pushb : public pushb{private: BUTTON_TYPE typ; // Storage room for the button type pushbuse *pt; // Stores a pointer back to the main objectpublic: // Method for making the button; void Create(widget parent, char *name, pushbuse *ipt, BUTTON_TYPE TYPE); // Method for catching button events; void pushed(void);};

class pushbuse : public mainwin{ // 'pushbuse_pushb' Should be able to access restricted methods; friend class pushbuse_pushb; private: vrow v1; // the main container hrow h1; // horizontal container htextf inputf; // input text field pushbuse_pushb okb,exitb; // push buttons MessageDialog mess; // dialog window nr. 1 QuestionDialog quest; // dialog window nr. 2

void exitquest(void); // Called when the ’exit’ button is pushed void sendtext(void); // Called when the ’fetch text’ button is pushedprotected: void buttonpushed(BUTTON_TYPE type); // Calls the right method when a button has been pushedpublic: // the constructor, makes the main window pushbuse(char *,int,char **);};

Program example for the pushb class,

continued;

Menus - ’Menu’

Menus are usually used in the main window, where the user often is presented with a lot of choices and possible actions. The choices are grouped along a line at the top of the window.

Appearance:Each section in the menu has a number of choices, represented by text. In addition, one can put toggle-buttons and separators in the separate pushdown menus. Ordinary sections are grouped from left to right, but the ”help”-section is usually placed at the rightmost corner.

Methods; void build(Widget parent, …) - Builds the component. The ’parent’ widget of the menu is usually the main container of the window, and the menu is the first item in this container. The arguments following ’parent’ is a number of strings that tells the ’build’ method what to insert into the menu. This collection of strings are terminated with a zero-pointer( see the example). If the string starts with ”STM:”, this tells the build method that a new group is to be inserted. If the string is ”SEP”, a separator is inserted. If it starts with ”T:”, a toggle-button is inserted and if the string starts with ”HLP:”, a help group is inserted. All other strings are considered normal items in a pushdown menu.

virtual void pushed(char *str) - A virtual method that is called when the user pushes a menu item. The method that calls pushed, sends along the string the user chose.

More about menus-methods and

program example

Here comes a program example using the Menu class. It’s simply called ”menuse(,C/H). menuse.H;

#include <mainwin.H>#include <dialog.H>#include <menu.H>#include <row.H>#include <label.H>#include <stdlib.h>#include <unistd.h>#include <string.h>

class menuse; // Tells about the existence of the main class

// implement a Menu class with a defined ’pushed’ method;class menuse_menu : public Menu{private: menuse *pt; // pointer back to the main objectpublic: void Create(widget parent, menuse *ipt); // creates the menu void pushed(char *menustr); // notifies the main object about menu events};

Program example -menuse.H

class menuse : public mainwin{ // 'menuse_menu' should be able to access restricted methods... friend class menuse_menu; private: vrow v1; // the main container label lab1; menuse_menu menu; // the menu itself MessageDialog mess; // dialog window void setcolor(char *color); // sets the colour void sendtext(char *messtext); // takes care of the ’fetch text ’eventprotected: void menupushed(char *menustr); // called when the user uses the menu // Called by menuse_menu...public: // Constructor. Makes the main windowmenuse(char *,int,char **);};

We’ve now made a Menu subclass with a defined pushed method and a pointer back to the main window object. The menu can thus tell the main window, when then user pushes a menu item.

Program example -menuse.C

#include "menuse.H"

// CREATE - Should build the menu and store a pointer back to the main object void menuse_menu::Create(widget parent, menuse *ipt){ pt=ipt; // store the pointer back to the main object // build the menu; build(parent,

"STM:File", // a new section in the menu, labelled ’File’"\”Fetch file\"","\”Write to file\"", // normal menu elements"T:On/off", // element with a checkbox. "SEP", // separator”Exit", // new, ordinary element"STM:Colours", // a new section in the menu"blue","green",”yellow", // elements under ’colour’"HLP:Help", // Help-menu section, will be shown to the right”About menuse", // elements in the help section...NULL); // terminate with NULL, in order to tell that

// there’s no more items in the menu}

// PUSHED - The menu has been used. Tell the main object void menuse_menu::pushed(char *str){ pt->menupushed(str); // tell which menu item that’s been pushed.}

// A menu item has been pushed. Find out which, and take action accordingly. void menuse::menupushed(char *str){

static Boolean onoff=False; // permanent storage of the on/off status

// Compare the incoming string with strings we know are in the menu; if(!strcmp(str,"\”Fetch file\"")) // tell which menu item has been pushed sendtext("\”Fetch file\" has been chosen!"); else if(!strcmp(str,"\”Write to file\"")) // tell which menu item has been pushed sendtext("\”Write to file\" has been chosen!"); else if(!strcmp(str,”On/Off")) {

// tell about the ”on/off” status onoff=!onoff; if(onoff)

sendtext("\”On\" is chosen!"); else

sendtext("\”Off\" is chosen!"); }

else if(!strcmp(str,"blue")) setcolor("blue"); else if(!strcmp(str,"green")) setcolor("green"); else if(!strcmp(str,”yellow")) setcolor("yellow"); else if(!strcmp(str,”About menuse")) sendtext(”This is a program for showing how the Menu class works"); else // If nothing else has been chosen, we’ll assume that ”Exit” has been pushed exit(0);}

Program example -menuse.C (2)

// SETCOLOR - Changes the colour of the main windowvoid menuse::setcolor(char *color){ v1.Background(color); menu.Background(color); lab1.Background(color);}

// SENDTEXT - Show a text in a dialog window. Used by menupushed to tell // which menu item has been chosen. void menuse::sendtext(char *textmess){ mess.build(mainwin::toplevel,"Message:",textmess);}

// CONSTRUCTOR -Make the main windowmenuse::menuse(char *title,int argc,char **argv) : mainwin(title,argc,argv){ v1.build(*this); // make the main container menu.Create(v1,this); // make the menu // Build a label that represent the contents of a main window lab1.build(v1,"Menu test ");}

// MAIN - functionmain(int argc,char **argv){ menuse mu("menu-applic",argc,argv); // make the main window mu.Run(); // run the application}

Program example -menuse.C (3)

Appearance and program flow -

”menuse”; This is the appearance of the previously listed program example. Themain window shows a Menu and a label.

or

Changes the colour of the main window

Shows a text message

Terminatesthe program

Single menu rows - ’SelOptMenu’

Sometimes one wants the menus other places than at the top of a window. If one has several choices that are connected to other components in the vicinity, it’s nice to present those choices at that place.

This menu is created using the SelOptMenu class,which makes the underlying widgets and handles user input.

More about ’SelOptMenu’

Methods in SelOptMenu: void Create(Widget parent, char *title) - builds this component in the parent widget ’parent’, and gives it the title ’title’. The title is presented right before the menu itself..

void Insert(char **list, int ilen, int focus) - Puts in the elements given in the string array ’list’, which should have length ’ilen’. Can set the focus to the given element, if that is wanted.

void SetFocus(int focus) - Sets the focus to the given element number, ’focus’.

char *CurrStr(void) - Returns the focused element as a string.

int GetNumber(void) - Returns the number of the element that has the focus right now.

virtual void Pushed(char *item) - A virtual method that is called each time the user uses the menu. Sends the newly focused element along as a string.

Checkboxes-’toggle’

There is often a need to enable the user to take an ”all-or-nothing” type of choice. The widget way of doing thisis by making a ’checkbox’ or ’toggle button’. This is implemented in Hydrasub by the toggle class. Here’s an example of how the widget looks like;

Outlook: or

’OFF’ ’ON’

Methods: void build(Widget parent, char *text) - Builds a widget in the parent widget named ’parent’, with the label ’text’.

virtual void pushed(Boolean on) - A virtual method that is started when the user pushes the toggle button. The method sends along the state of the checkbox (on=True or off=False).

void ToggleButtonOn(void) - Switches on the checkbox.

void ToggleButtonOff(void) - Switches off the checkbox

Boolean operator()() - Returns the state of the checkbox.

void SetLabel(char *str) - Changes the label of the checkbox.

Sets of toggle buttons - ’SelToggle’

A choice can often be between just a few options. One can use amenu for enabling the user to make such a choice, but a collection of checkboxes can illustrate the choice better. A set ofcheckboxes in a so-called ’radiobox’ will at maximum only have one box checked. This is implemented in the component called’SelToggle’.

Outlook;

The example is fetched from the program ’toguse’.

Methods: void hbuild(Widget parent, char **items, int len, int focus=0) - This method will build the widget, making a horizontal row of checkboxes with the given label(items) and the given number of checkboxes (len). The focus is given to the checkbox a position ’focus’. If this variable is set to zero, then no checkbox will initially be activated.

void vbuild(Widget parent, char **items, int len, int focus=0) - Works like the hbuild method, but places the checkboxes in a vertical column.

int operator()() - Returns the position of the focused checkbox.

void SetFocus(char *newfocus) - Activates the checkbox at the given position, giving the component a new focus.

virtual void pushed(char *item) - This virtual method is called each time the user activates a checkbox. The label of the checkbox is sent along.

An example using ’SelOptMenu’, ’toggle’ and ’SelToggle’

We’ll now make a program that uses a toggle button, a set of toggle buttons and a menu. While the single toggle button is activated, the contents of the menu and the toggle button set should be mirrored.

toguse.H:#include <mainwin.H>#include <menu.H>#include <row.H>#include <label.H>#include <toggle.H>#include <stdlib.h>#include <unistd.h>#include <string.h>class toguse; // tells that the main class exists

// TOGUSE_MENU// This is a subclass of SelOptmenu (pushdown menu)// that subscribes to user input by implementing the// 'pushed' method. Notifies the main object when // that method is called.class toguse_menu : public SelOptmenu{private: toguse *pt; // A pointer back to the main objectpublic:// Creates the menu, storing a pointer back to the main object void create(widget parent, char *title, char **items,

int length, int focus, toguse *ipt); // Called when an item is chosen by the user. Notifies the parent void pushed(char *menustr);};

// TOGUSE_SELTOG// This is a subclass of the SelToggle class (toggle button rows).// The 'pushed' method is implemented in order to handle // button events (notifies the main object).class toguse_seltog : public SelToggle{private: toguse *pt; // A pointer back to the main objectpublic: // Creates the toggle button row, string a pointer back to parent void Create(widget parent, char **items, int len,

int focus, toguse *ipt);// Called when th user pushes a toggle button. Notifies parent void pushed(char *togstr);};

// TOGUSE// This is the main window class and handles the int-// eraction between the menu and the toggle buttonsclass toguse : public mainwin{ // 'toguse_menu' and 'toguse_seltog' should be able // to access internal methods; friend class toguse_menu; friend class toguse_seltog;private: vrow v1; // the main container hrow h1; // container for the checkbox // component's label label lab1; // a label for explaining stuff toguse_menu menu; // menu component toguse_seltog seltog; // checkbox component toggle connectiontog; // single toggle button for // coupling/decoupling the menu and the checkbox // row

char **choices; // Stores the strings holding the name of the choices int choicelen; // The number of choicesprotected: // Called when the user pushes a menu item void menupushed(char *menustr);

// Called when the user pushes a toggle button // in the checkbox row; void togpushed(char *togstr);public: // Constructor // Makes the main window toguse(char *,int,char **);};

The program example ’toguse’

continues(2):

// TOGUSE// This is the main window class and handles the interaction// between the menu and the toggle button rowclass toguse : public mainwin{ // 'toguse_menu' and 'toguse_seltog' should be able to // access internal methods; friend class toguse_menu; friend class toguse_seltog;private: vrow v1; // the main container hrow h1; // container for the checkbox component's label label lab1; // a label for explaining stuff toguse_menu menu; // menu component toguse_seltog seltog; // checkbox (toggle) component toggle connectiontog; // single toggle button for // coupling/decoupling the menu and the checkbox row

char **choices; // Stores the strings holding the name of the choices int choicelen; // The number of choices

protected: // Called when the user pushes a menu item void menupushed(char *menustr);

// Called when the user pushes a toggle button in the checkbox row; void togpushed(char *togstr);

public:

// Constructor // Makes the main window toguse(char *,int,char **);};

toguse.C:

toguse.C:// TOGUSE// This is the main window class and handles the int-// eraction between the menu and the toggle buttonsclass toguse : public mainwin{ // 'toguse_menu' and 'toguse_seltog' should be able to // access internal methods; friend class toguse_menu; friend class toguse_seltog;private:

vrow v1; // the main container hrow h1; // container for the checkbox // component's label label lab1; // a label for explaining stuff toguse_menu menu; // menu component toguse_seltog seltog; // checkbox (toggle) component toggle connectiontog; // single toggle button for // (de-)coupling the menu and the checkbox row

char **choices; // Stores the strings holding // the name of the choices int choicelen; // The number of choices

protected: // Called when the user pushes a menu item void menupushed(char *menustr);

// Called when the user pushes a toggle button in // the checkbox row; void togpushed(char *togstr);public:

// Constructor // Makes the main window toguse(char *,int,char **);};

// CONSTRUCTOR // Makes the main windowtoguse::toguse(char *title,int argc,char **argv) : mainwin(title,argc,argv){ // Possible choices char *choicesbuff[]={"Choice number 1", "Choice number 2", "Choice number 3", "Choice number 4","Exit"}; choicelen=4; // the number of choices // Make a char** holding the list of choice strings choices=new char*[choicelen+1]; for(int i=0;i<choicelen+1;i++) { choices[i]=new char[100]; strcpy(choices[i],choicesbuff[i]); }

v1.build(*this); // make the main container

// Make the coupling/decoupling toggle button connectiontog.build(v1, "Couple the menu and the checkbox row:"); connectiontog.ToggleButtonOn();

// build the menu: menu.create(v1,"Choice, using a menu:", choices, choicelen+1, 1, this); // build the checkbox row; h1.build(v1); lab1.build(h1,"Choices, using the checkbox row:"); seltog.Create(h1, choices, choicelen, 1, this);}

// MAIN main(int argc,char **argv){ toguse tu("toggle-applic",argc,argv); // build the main window tu.Run(); // run the application}

The program example ’toguse’

continues(3):

The appearance and use of the

‘toguse’ program

The result will be ha handsome little “application”. One canset the option menu and thus change the state of the checkbox array, or select a checkbox an change the state of the menu. If the topmost toggle button is switched off, the connection between the SelOptMenu component and the SelToggle component is broken.

Two-colored pictures -

’pixelmap’Two-colored pictures can easily be inserted as a widget in Motif. Using the Hydrasub library, one can import a so-called xbm-picture with the command build in the ’pixelmap’ class. The example uses the ’nve_hest’ and ’nve_small’ sub-class, that presents a picture of the NVE-horse. (The library was developed at the Norwegian organisation NVE). Pictures of the xbm kind can be loaded and saved using xv or another pictures presentation program. Outlook:

Methods in ’pixelmap’:

void build(Widget parent, char *filename) - Makes a black-and- white picture, loading the X11-bitmap file ’filename’.

void build(Widget parent, char *filename, char*fground_color, char *bground_color) - Makes a pictures with a specified background and foreground color.

Methods in ’nve_hest’ and ’nve_small’:

void build(Widget parent) - Makes the NVE-horse in normal and small format.

The program component,

’header’ and ’header_lite’:

Outlook;

The component ’header’ and the smaller ’header_lite’ is madeas a standard way of presenting a program. They’re small layout ‘tricks’ made in order to give a uniform “look and feel” at thetop of a set of programs. The standard is showing the NVE-horse in the right-hand corner though the pixmap can be substituted. The ’header’ uses the pixelmap sub-class ’nve_hest’, in order to show the NVEW-horse. Similarly, ’header_lite’ uses the ’nve_small’ class.

Method: void build(Widget parent, char *title, int*spaces) - Builds a header component with the label ’title’ (in the example above; ”SerEdit 2.1”) and a small NVE-horse placed in the right-hand corner, with a label with ’spaces’ as the number of spaces in between the title and the pixmap.

The component for file selection -

’filesel’

One often want’s to enable the user to choose a file to save to or load from. There’s a standard component for such a procedure in Motif, and the ’filesel’ class is a C++ interface for this component.

Outlook:

Methods: void build(Widget parent, char *dir=”.”) - Makes the component and starts the file-listing in the given directory, ’dir’.

virtual void ok(char *filename) - This virtual method is called when the user pushes the ‘OK’ button. It sends along the filename that the user has chosen.

virtual void cancel(void) - This virtual method is called when the user pushes the ‘cancel’ button.

An example that uses the ‘text’ and ‘filesel’ class -

filetext

filetext.H:

// This program should allow the use to choose// a file using the file selection component in the // main window. Then the user pushes the 'OK' button,// a new window should appear, showing the contents // of the file in a text widget. The contents can be // changed in this widget and saved using the 'save'// button. (Thus the program can act as a primitive// text file editor.) If the user pushes the 'cancel'// button in the main window, the program is // terminated. //#include <mainwin.H>

#include <header.H>#include <row.H>#include <filesel.H>#include <shell.H>#include <text.H>#include <dialog.H>#include <pushb.H>

class filetext;// The class for the file selection component.// The methods for handling user events are defined here;class filetext_filesel : public filesel{private: // points back to the main window object; filetext *pt;

public: // creates the component, storing a pointer back to // the main object void Create(widget parent,filetext *ipt); void ok(char *filename); // handles that the user pushes the 'ok' button void cancel(void); // handles that the user pushes the 'cancel' button};

// This is a push-button class that notifies the main object, // when it's pushed;class filetext_savebutton : public pushb{ filetext *pt; // points back to the main window object;public: // creates the button, storing the main window pointer // and the button type; void Create(widget parent,char *text,

filetext *ipt);

// called when the user pushes the button; void pushed(void);};

// The main window class;class filetext : public mainwin{ friend class filetext_savebutton; friend class filetext_filesel;private: hrow h1; // the main container vrow v1,v2; // containers shell fileshell; // separate window text filelist; // text field for file listings closeshell closeb; // close-button for the sep. window filetext_savebutton savebutton; // saving-button header_lite hd; // header graphics filetext_filesel fsel; // file selection component ErrorDialog err; // error dialog window

char current_filename[200]; // should store the currently // chosen file nameprotected: // called when the user pushes the 'saving' button void savebuttonpushed(void); // called when the user pushes the 'ok' button in the file // selection component; void filechosen(char *filename);public:

// constructor: filetext(char *,int,char **);};

We’ll now examine a small program that fetches a file, showsthe contents of the file on the screen, enables the user to changethe contents and save it to the same file. This is in fact a small text editor!

filetext.C:

// PUSHED - tells the main window // object when the button is pushedvoid filetext_savebutton::pushed(void){ pt->savebuttonpushed();}

// Stores the contents of the text field // in the given filevoid filetext::savebuttonpushed(void){ ofstream out;

// checks if a file has been selected.... if(!current_filename) { // if not, notify the user; err.build(mainwin::toplevel,"Error",

"No file selected!!"); return; }

// opens the file for writing; out.open(current_filename,ios::trunc); // writes to the file; out << filelist.GetText();

// closes the file; out.close();}

#include "filetext.H"#include <fstream.h>#include <iostream.h>#include <stdlib.h>#include <unistd.h>

// CREATE - Makes a file selection component// Stores a pointer back to the main window objectvoid filetext_filesel::Create(widget parent, filetext *ipt){ pt=ipt; build(parent);}

// OK - The user has pushed the 'OK' button.// Tells the main window object about this...void filetext_filesel::ok(char *filename){ pt->filechosen(filename);}

// CANCEL - The user has pushed the 'cancel' button.// Exits the applicationvoid filetext_filesel::cancel(void){ exit(0);}

// CREATE - Creates a push-button and stores a // pointer back to the main// window object and the button typevoid filetext_savebutton::Create(widget parent,

char *text, filetext *ipt){ pt=ipt; build(parent,text); Background("green"); Foreground("black");}


filetext (2)

// FILECHOSEN - Sends the contents of a given // file to the graphic text fieldvoid filetext::filechosen(char *filename){ ifstream in; char line[1000];

// clear old contents of the text field t filelist.Clear(); //open the file for reading; in.open(filename,ios::in); // traverse the file; in.getline(line,999);

do { // send a line to the text field component filelist += line; filelist += "\n"; in.getline(line,999); } while(!in.eof()); // fetch the next line in the file

in.close(); // show the window with the text field; fileshell.Map();

// store the chosen file name strcpy(current_filename,filename);}

filetext.C:

// FILECHOSEN - Sends the contents of a // given file to the graphic text fieldvoid filetext::filechosen(char *filename){ ifstream in; char line[1000];

// clear old contents of the text field t filelist.Clear(); //open the file for reading; in.open(filename,ios::in); // traverse the file; in.getline(line,999);

do { // send a line to the text field component filelist += line; filelist += "\n"; in.getline(line,999); } while(!in.eof()); // fetch the next line // in the file

in.close(); // show the window with the text field; fileshell.Map();

// store the chosen file name strcpy(current_filename,filename);}


filetext (3)

The outlook of the’filetext’ program:

This is a filter that determines which files that are to be shown in the list to the right.

List of file directories

The ’OK’ buttonof the file selection component. In this program, pushing this button will fetch the contents of the file and show it in a separate window.

Quits theprogram

Header

Closes the window without saving the contents.

Saves the contents of the text widget to the chosen file.

Separations lines -’sep’, ’hsep’ and

’vsep’:The ’sep’ class is a layout element that is used to put a separation line in a window. To be used, an object must belong two one of it’s two sub-classes,’hsep’ (horizontal separator) or’vsep’ (vertical separator). One can use the standard type or choose from a set of defined separator types defined in separator.H.

Example of the outlook of the sep class:

Methods: void build(Widget parent) - Builds a standard separator. void build(Widget parent, SEPTYPE type) - Builds a separator of the given ’type’. (See separator.H.)

The program listuse, is an example program that uses the sep class,see later in the text.

Marking a separate area in a window -

’frame’:

In order to improve the layout of a window, one might wish to mark a certain area of it. This can be done with the “frame” widget. One can think of ’frame’ as a container that only allows one sub-widget (but this can be another container.)

An example showing the outlook of the frame widget.

Methods: void build(Widget parent) - makes a ’frame’ around whatever is placed inside this widget.

For an example that uses this class, see listuse.C/H.

Text lists, the ’list’ class

There’s often a need to present the user of a choice between a great but finite number of possibilities where each possibility is presented as a text. In order to enable the user to make such a choice, the ‘list’ widget was made. It looks a lot like the ‘text’ widget, but each line is selectable. This means that the user can choose a line of text and the program will ‘know’ which line and which text was chosen. This can be done immediately after the user has chosen a line or when the program finds it convenient to retrieve that information.

An example of the outlook of this widget;

Methods: void build(Widget parent, int rows, int hor_scroll_bar=0) - Builds a list with ’rows’ number of visible rows. One can use the toggle variable ’hor_scroll_bar’ for letting the widget use a horizontal scrollbar when that is convenient. The default is for this not to happen.

virtual void OneHit(int pos, char *contents) - This virtual method is called whenever the user chooses a line in the widget. The chosen text string and text line is sent along.

list operator+=(char *) - Inserts a new line into the widget..

void Insert(char *elementstr) - Also inserts a new element.

void Inserts(char **elements, int len) - Inserts a string array of elements of length ’len’.

void Delete(int pos) - Removes the element at the given position, ’pos’.

void Clear(void) -Removes all elements in the list.

void ClearSelected(void) - Removes the elements that the user has marked.

void MarkAll(Boolean policy=False) - Marks all elements.

void Mark(int pos) - Marks the element at position ’pos.

void RemoveMark(int pos) - Removes the marking at the position ’pos’.

int Selected(void) - Returns the position of the first marked element.

int Selected(int **poslist) - Returns the number of selected elements and the position of each of them in the ‘poslist’ array.

int ExistsInList(char *element) -Checks if the text string ’element’ exists in the list.

Text lists, the ’list’ class (2)

void SetActive(int pos) - Marks the position ’pos’ and will cause the ’OneHit’ method to be called.

int NoInList(void) - The number of elements in the list.

int Get(char ***str) - Returns the number of elements in the list and the string array representing each element in the list.

In the ’list’ class itself, one can only have one marked line at a time. In the sub-class ’multiplelist’ however, one can have as many marked lines as one wants. A few of the listed methods are mainly made for this sub-class.

Text lists, the ’list’ class (3)

A program example that uses the ’list’ class, listuse.C/H:

#include <mainwin.H>#include <list.H>#include <row.H>#include <textf.H>#include <dialog.H>#include <label.H>#include <separator.H>#include <frame.H>

class listuse;

// OPERATIONLIST// An object of this class, represent the leftmost list, where// user interactions is captured.class operationlist : public list{private: listuse *pt; // pointer to the main window // layout widgets; frame fr; hsep sep; vrow v1; label lab;

public:

// This method creates the list and stores a pointer back // to the main window void Create(widget parent,int rows,char *title,

char **elements, int len,listuse *ipt);

// This method is called when the user pushes an item in the list. // Notifies the main window void OneHit(int pos,char *contents);};

We’ll now make a program that takes commands from the user in theform of a list. The commands together with an input text field willdetermine the state of another list in the rightmost corner of the window. Elements in the rightmost list can be inserted, marked, demarked and removed using the “command” list to the left. The widgets ’sep’ and ’frame’ are used for layout purposes.

listuse.H:

// LISTUSE// An object of this class represent the // main windowclass listuse : public mainwin{ friend class operationlist;private: hrow h1; // the main container multiplelist ownlist; // the rightmost list operationlist op; // the leftmost (operation) list vtextf inputf; // the text input field MessageDialog mess; ErrorDialog err; vsep sep; // separator

protected: // Called when the user hits the // leftmost list void operhit(int pos,char *contents);

public: // the constructor, makes the // main window listuse(char *,int,char **); };

listuse.C:

A program example that uses the ’list’ class, listuse.C/H

(2):

#include "listuse.H"#include <stdlib.h>#include <unistd.h>#include <string.h>

// Make a component with a title, a list and// a 'frame' around it and with a separator between...void operationlist::Create(widget parent,int rows,

char *title, char **elements, int len,listuse *ipt)

{ fr.build(parent); // frame around the comp. v1.build(fr); // container lab.build(v1,title); // title label sep.build(v1); // separator build(v1,rows); // the list itself Inserts(elements,len); // put elements into the list // initialise the pointer variable pt=ipt;}

// An element has been chosen. // Tell the parent window;void operationlist::OneHit(int pos,char *contents){ pt->operhit(pos,contents);}

// Takes care of user input from the list to the // left by manipulating the list to the rightvoid listuse::operhit(int pos,char *contents){ char str[100];

switch(pos) // depending on the position of the list hit... { case 1: // append the list strcpy(str,inputf()); // fetch the contents of the text field

if(str && *str) // if we have any content... { // check if the string is already in the list; if(ownlist.ExistInList(str)) // if so, show an error dialog window err.build(mainwin::toplevel,"Error", "the element already exists in the list!"); else // if not, insert the string into the rightmost list ownlist.Insert(str); } else // no content in the field, show // an error dialog window err.build(mainwin::toplevel,"Error", "No text in the text field!"); break; case 2: // Select all ownlist.MarkAll(True); break; case 3: // De-select all ownlist.MarkAll(False); break; case 4: // Remove the selected elements ownlist.ClearSelected(); break; case 5: // Remove all elements ownlist.Clear(); break; case 6: // list the marked elements { int sellen,*poslist; int len; char **totalstr; char *ptr,strlist[1000];

// fetch the marked rows len=ownlist.Get(&totalstr); // fetch all the list strings sellen=ownlist.Selected(&poslist);

Listuse.C: case 8: // quit exit(0); }}

// The constructor// Makes the main windowlistuse::listuse(char *title,int argc, char **argv) : mainwin(title,argc,argv){ // legal operations char *operations[]={"Append text", "Mark all", "Mark nothing", "Remove marked rows", "Remove all elements", "List the marked elements", "List all elements", "Quit"};

// Start-contents in the rightmost list; char *init_elem[]={"init 1","init 2", "init 3"}; int init_len=3; // Number of starting elements

h1.build(*this); // main container // operation list: op.Create(h1, 5, "Operations:", operations, 8, this); // input, text field: inputf.build(h1,20,"New element:"); sep.build(h1,DOUBLE_LINE); // separator ownlist.build(h1,5); // rightmost list ownlist.Inserts(init_elem,init_len); // initialise this}

// Make a text presentation of this; strcpy(strlist,"Chosen elements:\n"); ptr=strlist+strlen(strlist); for(int i=0;i<sellen;i++) { sprintf(ptr,"%s\n", totalstr[poslist[i]-1]); ptr=strlist+strlen(strlist); }

// present the text; mess.build(mainwin::toplevel,"Message:", strlist); break;}case 7: // show all the elements{ int len; char **totalstr; char *ptr,strlist[1000];

// fetch all the strings len=ownlist.Get(&totalstr);

// Make a text presentation of this; strcpy(strlist,"Elements:\n"); ptr=strlist+strlen(strlist); for(int i=0;i<len;i++) { sprintf(ptr,"%s\n",totalstr[i]); ptr=strlist+strlen(strlist); }

// present the text; mess.build(mainwin::toplevel,"Message:", strlist); break;}

A program example that uses the ’list’ class, listuse.C/H

(3):

The outlook of the ’listuse’ program:

main(int argc,char **argv){ listuse l("listuse",argc,argv); // Make the main window l.Run(); // run the application}

Listuse.C:

Outlook andexample of use;

Pushing the row labelled“append text” resultsin the contents of thetext field being insertedinto the rightmost list.

Marking two elements and pushing the“list marked elements” row...

...results in a message window listing the chosen elements.

Containers that can be scrolled -

’scroll’

One can wish to present a large number of similar components atthe same time. This can result in the window getting too large for the screen. In this case, it can be sensible to use the ’scroll’ class. An object of the class ’scroll’ can only have one sub--widget, but this widget can be a new container.

Outlook;

The scoll container surrounds the contents in this picture.

Methods: void build(Widget parent) - Builds a scroll’ widget.

It can often be smart to use the Width and Height methods fromthe super-class widget (see page 1-3)

The scrollbar itself

The contents

Setting a number using a

slider - ’scale’:

If one wants to enable the user to choose a number between twoextremes, one can use the ’scale’ class. This is a virtual classthat has two complete sub-class namely ’vscale’ (vertical scale) and ’hscale’ (horizontal scale). The example below usesthe hscale class;

Example of the outlook;(horizontal scale):

Methods: void build(Widget parent, char *text, int min, int max, int value) - Makes a slider with the text ‘text’ and with the a given minimum and maximum value. The starting value is specified using the ‘value’ variable.

int operator()() - Returns the current value of the slider set by the user.

A drawing area - ’draw’

One often needs to display plots and other forms of advanced graphics on the screen. The ’draw’ class is built to facilitate suchpresentations. The example below is from a plotting module.

One example of the outlook;

Methods:

void build(Widget parent, int width, int height) , Boolean dodrag=False, char *postscriptbufferfile=NULL) - Makes a drawing area with the given width and height. If the ‘dodrag’ variable is set, the virtual methods motion_started, motion_ended and draw_motion_object will be called. The default is that these routines draws a rectangle around a selected area. The virtual method boxed will be called when the user releases the button. If the postscriptbufferfile variable is set, the drawing will take place on a postscript file in addition to the drawing area on the screen.

void do_background(char *postscriptbufferfile, int width, int height) - The ‘plotting’ will be redirected to a postscript file. No screen output.

More methods in the ’draw’ class:

void SetFg(char *color) - Sets the foreground color to the given color. (Can be of the type “#rrggbb”, where rr, gg and bb is the hex code (0-255) of the red/green/blue intensity.

void SetLineWidth(int width) - Sets the line width.

void SetFont(char *font) -Changes the font.

void Line(int x0,int y0,int x1,int y1) - Draws a line between the point (x0,y0) and the point (x1,y1).

void Point(int x,int y, DRAW_POINT_TYPE type=

DRAW_POINT_PIXEL) - Makes a dot at the point (x,y). Different point styles can be chosen using the ‘typ’ variable (see draw.H).

void Text(char *str,int x, int y) - inserts a text that starts at the point (x,y).

void Clear(char *color="black") - Clears the drawing area and sets the background color.

void Getgeom(unsigned int &width, unsigned int &height) - Returns the width and height of the drawing area.

void GetFontGeom(unsigned int &width, unsigned int &height) -fetches the font size.

void do_invert_black_and_white(void) - Inverts black and white in the screen output. (Useful when one wants black background on the screen and white background on a postscript output, forinstance during plotting.)

Boolean black_and_white_inverted(void) - Returns ‘True’ ifreversed black and white is set.

void Set_Dashes(char *dashlist, int length, int linewidth) - Setsthe next lines to be drawn to be dashed. The dashlist is an arrayof small numbers that specifies the length of each dash. The widthof the lines is also specified.

void Set_No_Dashes(int linewidth) - Sets that no dashes are to be used during line drawing. Also sets the line width.

void Lines(double *xvalues, double *yvalues, int arraylength,double x0=0.0, double y0=0.0) - Draws a number of lines fromthe first point (xvalues[0], yvalues[0]) to (xvalues[1], yvalues[1])etc. These two arrays should have the specified array length, arraylength. The origin is set at the point (x0, y0).

void circle(double x0, double y0, double r, Boolean filled=False,double startarc=0.0, double numarc=360.0) - Draws a circleat the given coordinate (x0,y0) and the given radius, r. One can setthe circle to be filled by setting ‘filled’ to true. If a semi-circle isto be drawn, one can set the start and end angle using, startarc,numarc.

More methods in the ’draw’ class

(2):

void plotlines(double *xvalues, double *yvalues, int arraylength) - This method, which is used in the plotting module, requires that thepoints in the xvalues array is increasing. If the lines are drawn closeto each other (the array length is large), only the minimal and maximal values inside a pixel will be draw. This enables a more efficient plotting.

Boolean load_softfonts(char *fontfile=NULL) - This method willtry to load ‘soft’ fonts from the given file. The file should containbitmaps of the type one can find on the Hydrasub/lib area. (See forinstance pc8x16s.bdf.) This is done in order to draw tilted text.It might often be used more easily than it’s “hard font” counterpart,SetFont, as the font file comes with the distribution of Hydrasub, while different machines have different hard fonts.

void soft_text(char *str, int x, int y, double angle,int font_size=MISSING_VALUE) - Draws a soft font text from agiven point (x,y) and a given angle. The font size can be specified.

void endpostscript(void) - Terminates the postscript output. Ifmore drawing is done, the postscript file will be remade.

void Rectangle(double x0, double y0, double x1, double y1,Boolean filled=FALSE) - Draws a rectangle from (x0,y0) to (x1,y1).

void do_xor(void) - Draw using XOR logic. Used during dragging.

void do_or(void) - Draw using OR logic.

void do_copy(void) - Draw over the previous contents


(3):


(4):

More methods;

virtual void expose() - Called each time the drawing area should bedrawn. No drawing should be done before the system calls this method.Thus it’s natural to put most or all the drawing that is to be doneinside this method.

virtual void resize(int x , int y) - Called each time the drawing areais resized.

User interface methods;

virtual void DoButton1(int x, int y) - Called when the user pushes theleft mouse button in the drawing area.

virtual void DoButton2(int x, int y) - Called when the user pushes the middle mouse button in the drawing area.

virtual void DoButton3(int x, int y) - Called when the user pushes the right mouse button in the drawing area.

virtual void Boxed(int x1, int y1, int x2, int y2) - Called when the user has done a drag operation in the drawing area. (Requires thedodrag variable in the build method to have been set.)

virtual void DoUp() - Called when the user pushes the “arrow up”keyboard key, while the drawing area is active. (to be sure that thedrawing area takes the keyboard input, it should be the only widgetin the window that can be activated, with the exception of a top menu.)

The ‘draw’ class has a sub-class called ’drawgif’. This class ismade in order to display GIF images. It uses the old GD-library inorder to do so.

Methods: void build(Widget parent, char *gif_filename) - Fetches a GIF image and displays it.

The ’drawgif’ class

virtual void DoDown() - Called when the user pushes “arrow down”.virtual void DoLeft() - Called when the user pushes “arrow left”.virtual void DoRight() - Called when the user pushes “arrow right”.virtual void DoPageUp() - Called when the user pushes “Page Up”.virtual void DoPageDown() - Ditto for “Page Down”.… There’s lot’s of method’s like these. One for each special key.virtual void DoKey(char c) - Called when the user pushes a non-special key.


(5):

hypertextIt might be useful to present a clickable text, much like a labelwith user feedback. This is done using the draw class and it’stext methods. When the user clicks the hypertext, this actioncan be ‘linked’ to another action. (In a browser it would cause theapplication to move to a new web page). In another applicationit might be useful to display the meaning of a difficult word if the user pushes the hyperlink.

The widget looks like this (sorry for the Norwegian text);

Methods;

void Build(widget parent, char *txt) - Makes a hypertext with the given string, txt.

virtual void pushed(void) - A virtual method that is called when the user pushes the hyperlinked text.

A class for timing events - timer

The Xt library contains code for making a clock period and event.One can tell the application to run a given routine after a given time(in number of milliseconds). Theses procedures can be reachedthrough the Hydrasub library by the use of the ‘timer’ class. Thisis a virtual class that can be put as a super-class of the window/widgetyou want to use this functionality on. The class containsa method for setting the next ‘wakeup’ call and a virtual method that is called when the given amount of time has passed.

Methods; void Set(unsigned long millisec) - Sets the wakeup to happen in the given amount of milliseconds. virtual void wakeup(void) - Called when the given amount of milliseconds has passed.

A module for sending email -

’email’

It might be nice to send email from an application. Thiscan be done with the ’email’ module. It’s a shell window with a few text fields used for setting the receiver andsubject. There’s a large text area for the actual contents of the mail and a list of attached files. At the bottom of thewindow there’s a couple of buttons, one for sending the email and one for closing the window. The module uses /usr/lib/sendmail to do the actual operation of sending theemail.

Outlook(not theWindowsmail prog):

Sender

Receiver

Subject

Closebutton

Sending theemail

Attachment list

Message body

Attaching a new file

Remove from attachment list

Methods in ’email’

Methods: void Create(char *receiver=””, char *subject=””, char *start=””) - initialises the module and makes the window. The receiver is initially set to ’receiver’, the subject line is initially set to ’subject’ and the start of the message body is initially set to ’start’.

Boolean addfile(char *file) - Puts the contents of the given file into the message body.

Boolean attach(char *file) - Puts the given file into the attachment list.

virtual void ended(void) - Called when the user pushes the ‘close’ button.

There is also a sub-module called ‘email_module’ that represents the contentsof the window (but not the window itself). It can be used when one want’s theemail functionality integrated into a larger window or as the contents of themain window.

A module for making value-value and time-

value plots - ’plot_module’

The plotting module in this library is a rather large piece of code.We’ve tried to limit the number of calls necessary for integratingit into an application though. The programmer interface is relatively simple. This means that it’s pretty straight forward to use it in an application, but that it has only a (relatively) small amount of options to be set.The programs that so far has been made atop of this module reflects that philosophy (timeseriegraph, vvgraph and showfunc).

Outlook (taken from theshowfunc program);

The module usually pops up in it’s own window, with a top menu wherethe user can tweak the appearance of the plot or navigate 8zoom) in the plot. The user can also send the contents of the drawing area to a printer, tothe email component or to a file (gif, eps or a few other formats, using ImageMagics ‘convert’ program). The plot can also be put as a part of a larger window or the whole plotting can occur on a file in stead of the screen. The methods available to the programmer is found at the endof ‘plot_module.H’ as the public methods of the ‘plot_module’ class.

Methods in ’plot_module’

These are the most important methods in this module;

void Create(double **arg, double **val, int *length, int *yaxis, char **linetitles, int numseries, char **axistitles, int numaxis, // ...necessary parameters // options; char *title_=NULL, PLOTLINE_TYPE *plottype=NULL, int *xaxis=NULL, PLOTLINE_STYLE *style=NULL, char **colorname=NULL, int *width=NULL, Boolean *logarithmic_axis=NULL) -

Note that Create(&arg, &val, &length, &linetitle, 1, axistitles, 2) would be enough to show a single line plot in an application. The length of each argument array element, arg, and value ,val, is set by the length array. The number of plotting lines (graphs) are set by numseries, which thus specifies the size of the array of arrays. The linetitle string array should contain the label of each graph, while the axistitles string array should contain the label of each axis (normally only two, one x-axis and one y-axis). The numaxis variable specifies the number of axis. The yaxis array specifies what y-axis each graph belongs to (usually axis number 1).

The options are as follows; The title_ variable can give the plot a header atop of the other elements. The plottype array specifies weather lines, dots or bars are to be used. The xaxis array specifies which x-axis each graph belongs to (if more than one x- axis is wanted). The style array specifies the plotting style of the line or dots representing each graph. (See plot_module.H) The colorname array specifies the color of each graph. The width array specifies the line width of each graph. The logarithmic axis variable toggles logarithmic x- and y-axis.

There is also a Create method which takes an array of DateTime elements as an argument. This makes it possible to show a timeserie graph using this module. The plot will show years, months, the days in a month and the hour and minute too,if these are required. Except for the argument array type, the method looks much the same as for value-value plots;

void Create(DateTime **arg, double **val, int *length, int *yaxis, char **linetitles, int numseries, char **axistitles, int numaxis, char *title_=NULL, PLOTLINE_TYPE *plottype=NULL, PLOTLINE_STYLE *style=NULL, char **colorname=NULL, int *width=NULL, Boolean *logarithmic_axis=NULL) - See the other Create method.

virtual void plot_ended(void) - Called when the user has pushed the “close window” menu item.

void set_background(char *filename_without_extensions, int width, int height, IMAGE_TYPE typ=EPS, Boolean toprinter=False) - This method should be used before the Create method in order to make the plot go to a file rather than to the screen. The file name and the dimension of the image must be given. One can also specify the image type, typ, see “filesel.H”. One can toggle a tilted image in order to use the whole paper when sending the postscript file to a printer. If that is wanted, set the toprinter variable

void put_in_widget(widget parent, int width, int height, PLOT_TYPE plottype=PLOT_IN_WIDGET_SHOWMENUES) - This method should be called before create in order to put the plotting area in a larger window in stead of making it’s own. The parent widget and the dimension of the plotting area should be specified. One can also set the policy for the menus and the zooming using the plottype variable, see “plot_module.H”.

Methods in ’plot_module’ (2)

void set_grid(Boolean gridstatus) - Used before the Create method in order to toggle showing grid lines in the plot.

void set_vertical_yaxis_titles(Boolean status) - Toggles whether the labels of the y-axis should be vertical or horizontal. Default is vertical.

void set_min(double new_min=MISSING_VALUE, int axis_index=1) - Sets the minimal value for a given y-axis. MISSING_VALUE (the default) makes the minimal value be set according to the minimal value of the graphs using this axis.

void set_max(double new_max=MISSING_VALUE, int_axis_index=1) - Set the maximal value for a given axis.

void set_radial(double circle_length=MISSING_VALUE, Boolean start_yaxis_at_zero=True) - Toggles a radial (polar) value-value plot rather than a Cartesian plot. If the circle_length is missing, a Cartesian plot is made, else the circle length specifies the circumference of the circle (the system for the ‘angle’ component which the x-axis now is). If the start_yaxis_at_zero variable is not set, the module uses the minimal value of the graphs as a reference point.Multiple x-axis should not be used!

void set_radial(long int minutes=MISSING_VALUE, long int years=MISSING_VALUE, Boolean start_yaxis_at_zero=True) - Toggles a radial (polar) timeserie plot. The circumference of the circle is specified by the minutes and years variables. If the start_yaxis_at_zero variable is not set, the module uses the minimal value of the graphs as a reference point.

void set_big(void) - Toggle text and bold lines.

Methods in ’plot_module’ (3)

An example using ’plot_module’ -

plotuse.C;

This is an example that shows how the plotting module is used in a program;

#include <plot_module.H>#include <math.h>

class quitb : public pushb // 'quit' button {public: void pushed(void) {exit(0);} //inline definition of the action};

#define LEN 500void main(int argc, char **argv){ // defining the widgets;

mainwin mn("plotuse", argc, argv); // make the main window vrow v1; // main container plot_module plot; // the plotting module quitb qb; // the 'quit' button

// variables needed for making the plot;

// argument and value array; double *arg=new double[LEN], *val=new double[LEN]; // axis titles and the graph title string; char **axistitles=new char*[2], *linetitle=new char[100]; int len=LEN, axis=1; // the graph length and the axis it's attached to register int i; // index

for(i=0;i<LEN;i++) // traverse the argument and value array { arg[i]=-2.0*M_PI+double(i)/LEN*4*M_PI; // set the argument val[i]=sin(arg[i]); // set the value }

// make the axis titles and the graph title; axistitles[0]=new char[100]; strcpy(axistitles[0], "x-axis"); axistitles[1]=new char[100]; strcpy(axistitles[1], "y-axis"); strcpy(linetitle, "sin(x)");

v1.build(mn); // build the main container

// tell the plotting module to build itself in the main container plot.put_in_widget(v1, 800, 600);

// build the plotting area; plot.Create(&arg, &val, &len, &axis, &linetitle, 1, axistitles, 2);

// build the 'quit' button qb.build(v1, "Exit");

// The arrays should be freed here, but since they're not big // memory hogs we'll not do this, for simplicity sake.

mn.Run(); // run the application}

An example using ’plot_module’ -

plotuse (2)

The program will look like this;

Quit the “application”

Menus in the screen-output of

’plot_module’

Toggle grid lines

Here one can toggle the use of logarithmic x- and y.axis. The minimal value has to be set.

Here one can change details in the presentation of each graph. Thecolor, line text, graph type (dot, line or bars) and line type can be changed here.

The plot title and the axis titles can be changed here

Interpolation overmissing values rangingno more than the given gap length, can be set here.


’plot_module’ (2)

The navigation menu shows methods for zooming in and out of the plot. It also shows key shortcuts for these choices.

This window allows for specificchanges in the plotting range.

The “Send:To file” option starts a windowallowing the user to set the image size.When a size is choices, a file selection windowis started (a sub-class of filesel called “image_filesel”, used for allowing the user to specify an image type). If anything otherthan Postscript is chosen, the module thenuses the program ‘gs’ and the ‘convert’ program from ImageMagic to convertthe picture to the given format.


’plot_module’ (3)

This window makes it possible to change the printer.

Abort the printingDo the printing

If the “Send:To printer”option is used, a windowpops up making the user able to change his printeror do the printing job. The window for allowing the user to change printer is implemented in the “printershell” class in the PrinterList.C/H file.

If the “Send:As email” option is chosen, a window pops up that allows the user to choose the image type and the image size.If the user pushes the ‘OK’ button, theemail class is used to enable the userto send the image as email. (Again ‘gs’ and ‘convert’ is used if the user specifies anything other than Postscript as the image format.)

Trond Reitan, 28/5-2001

Other classes and procedures.

There’s a bit of code used in the ‘hydragui’ library that’s implementedin the hydrabase library. Some simple non-GUI procedures and the DateTime are found there.

Large modules, like the ‘email’ or (most significantly) the plotting module uses a lot of classes defined early in their header files. Theseclasses and methods are usually connected to the larger modules, andare therefore not covered here.

There are a few classes we’ve covered rather lightly, like the‘onlydatetime’ text fields and the ‘image_filesel’ file selection window.They’re rather specific and their usage is quite like their super-classes.

The “PrinterList” classes are not covered in order to keep this presentation “brief”. They use the “/etc/printcap” file in order to builda list of possible printer to send output to. If the user chooses a printerthe “PRINTER” environment variable is changed accordingly.

The “lineage” class is not covered here, as this module is rather specific andnot of interest to most programmers. It’s a module for presenting thecontents of different ‘creatures’ or objects that are interrelated to eachother through parent-child bonds. The module is used for presentationpurposes in evolution simulations. It uses the draw class as well asthe plotting module and a host of other GUI components, and as such is the topmost module here.

The ‘showneural’ class is a module for showing how a neural network is built. (Showing the neural ‘cells’ and the connectors between them.

The ‘viewcolor’ class allows the user to choose a color using sliders for the red, green and blue values.

Documents

HYDRASUB GUI, A C++ wrapper library for Motif