Previous Next Contents Generated Index Doc Set Home


CHAPTER 17

Thin Client Smart Code





Introduction

Motif and MFC applications are traditionally large scale applications. Modern Internet technologies encourage the thin client approach. This is an application structure with a clean division between:

A lightweight client controlling just the user interface.
A remote server providing data back to the client.

Note - The server application generated by default by Sun WorkShop Visual is a CGI program using a Web server to communicate with the client.
This chapter describes how Sun WorkShop Visual helps you to migrate, very simply, from a large scale application to the structure described above. This is achieved by first "grouping together" widgets to create portable data structures, then "enhancing" your callbacks so that they can either run remotely or communicate with a remote server. There are no other changes you need to make to your design.

Sun WorkShop Visual also lets you try out the connection between the client and the server dynamically before you generate code. Setting the "Go Live!" toggle for a thin client or Internet callback activates that callback by connecting to the specified URL. This is described in Going Live.

You will need to understand how to use both Groups and Get/Set Smart Code in order to use the thin client (or Internet) Smart Code because Groups, along with their getters and setters, are the nuts and bolts of all types of Smart Code. Information on these subjects is found in:

  1. The grouping together of widgets is described in Chapter 15, "Groups".
  2. Chapter 16, "Get/Set Smart Code" describes the Get/Set Smart Code which provides you with toolkit-independent wrappers for the widgets in your design.


Using Thin Client Smart Code

Creating a thin client and server application from your design is done by setting up a special Smart Code callback. To do this, you only need to do the following:

  1. Display the Callbacks dialog for a widget in your design.
  2. Select the "Smart Code" toggle.
  3. Choose "Thin Client" from the Smart Code option menu.
  4. Specify a Group.
  5. Name and add the callback.
What a Group is, and how to create one, is described in Chapter 15, "Groups".

Smart Code gives your callback toolkit-independence, not language independence. You still choose the language you wish to generate. Smart Code is simply a layer of code which "wraps up" the widgets in a Group using the specified language.

There are three types of Smart Code:

  1. Get/Set. This provides you with a suite of "getter" and "setter" functions for a group of widgets. This is described in Chapter 16, "Get/Set Smart Code".
  2. Thin Client. This provides not only the getters and setters, it also triggers Sun WorkShop Visual to generate a separate thin client application containing the user interface and a server application containing the callback you are defining. In addition, the code to handle the communication between the two is generated. This chapter describes the use of thin client Smart Code.
  3. Internet. This also provides the getters and setters and tells Sun WorkShop Visual to generate a client application which is ready to communicate with a remote server. The code for communicating with the server is also generated. Internet Smart Code is described in Chapter 18, "Internet Smart Code".

Specifying a Group

Both "Thin Client" and "Internet" Smart Code styles require the name of a Group to be passed to the callback. The Group gives the callback access to data in the user interface, even though the callback may be running in a remote server. Either type the name of the Group directly into the "Group" text field or press the "Group" button. This displays the Group Editor. Select the Group you require and press "Apply" to both dismiss the Editor and place the name of the Group into the text field.


Getters and Setters

All of the stubs generated by Sun WorkShop Visual when either "Thin Client" or "Internet" is selected, have full use of the "getter" and "setter" routines for the specified Group. The Get/Set Smart Code is described in Chapter 16, "Get/Set Smart Code". The callback in a server has a slightly different access to the Group components. It calls a single get or set routine which accesses a default "value". This "value" differs according to the type of widget. For example, a text field has a string value (its contents) and a toggle has a boolean value (its state).


Customize Button

Sun WorkShop Visual Selecting "Thin Client" or "Internet" from the Smart Code "Style" option menu in the Callbacks dialog enables the "Customize" button. This button displays the Customize dialog, allowing you to configure how data is sent to and received from the server. Sun WorkShop Visual does provide sensible defaults. You will always have to change the URL address of the server with which you are communicating, however.

The Customize dialog appears slightly different according to whether it is displayed with "Thin Client" or "Internet" selected from the option menu. The only difference is the label for the Send custom data handler text
box. This is because Sun WorkShop Visual uses a different HTTP method for the two types of application. When "Thin Client" is selected, Sun WorkShop Visual uses the POST protocol. By default, Sun WorkShop Visual uses the GET protocol when "Internet" is selected because it is assumed that you are only fetching web pages. You can change this to use POST by providing a custom Send data handler. More about this is given in Custom Data Handlers.

The Customize dialog is explained in "Customizing the Server Connection" below.

See Thin Client/Internet Generated Code for details of the code that is generated when a server callback is defined, including a list of the stubs files.


Go Live

The "Go Live!" toggle becomes sensitive when a thin client or internet callback has been defined. Setting the toggle enables you to test the connection between the client and the server from within Sun WorkShop Visual, before generating code. Detailed information on this is given in Going Live.


Requirements

Both thin client and Internet Smart Code styles use the standards of the World Wide Web as the means of communication between the generated client application and a server. In order to run the generated and compiled applications and to use the "Go Live" feature, you will need:

  1. A networked computer connected to an Intranet or Internet.
  2. A running Web server.
If you need more information on this, consult your systems administrator or contact your Sun WorkShop Visual supplier.


Thin Client Smart Code Tutorial

This simple tutorial gives you the chance to try out the "Thin Client" style of Smart Code. By following these steps you will quickly generate a thin client containing the user interface shown in Figure 17-1 and a server which sets the contents of the text field according to whether or not the toggle is set. The server can run remotely on your own intranet or anywhere on the Web.

The initial steps are covered only briefly as it is assumed that you are already familiar with the general use of Sun WorkShop Visual. If you are not, you may wish to try the main Sun WorkShop Visual tutorial which starts in Chapter 2 "Building the Widget Hierarchy".

FIGURE  17-1 Thin Client Application User Interface

  1. Start Sun WorkShop Visual.
  2. Create a simple hierarchy: application shell->form->button, label, toggle, text field.
    This is shown in Figure 17-2.

FIGURE  17-2 Hierarchy for Smart Code Tutorial

  3. Label the button "Go", the toggle "Check me" and the label "Text:".
  4. Give the shell the title "Tutorial Example".
    Do this in the shell's resources dialog.
  5. Display the Form Layout Editor and lay out the widgets so that they look roughly as shown in Figure 17-3.
    This is a purely cosmetic change. It affects only the appearance and has no impact on the function of the application.

FIGURE  17-3 Tutorial Widgets Laid Out

  6. Make the toggle and the text field a Group called "MyGroup".
   
If you can't remember how to do this, see Creating a Group.
There is a lot more information about Groups in Chapter 15, "Groups". The Get/Set Tutorial is a simple example which shows you how to create and use a Group.

  7. Select the button and display the Callbacks dialog.
  8. Type "doGoButton" into the function name text box.
    This callback will, in effect, move to the server-side of your application.
  9. Set the Smart Code toggle button.
  10. Change the Smart Code style to "Thin Client".
    When you do this, the "Customize" button is enabled.
Much more detail concerning the use and meaning of "Thin Client" is given in "Thin Client Server Callbacks" section.

  11. Press the "Customize" button to display the Customize dialog.
    The dialog is shown in Figure 17-4.
The various fields in the Customize dialog are described in "Customizing the Server Connection" section.

FIGURE  17-4 Customize Dialog

  12. If you are behind a firewall, fill out the proxy and port fields.
    If you are not sure about this, check with your system administrator or see how your web browser is configured.
"More on Proxies" section lists ways of finding out what your proxy is.

  13. Make sure that the URL field refers to the name and location of your server program.
    For example:

	http://localhost/cgi-bin/untitled
    would refer to a server named "untitled" located in the "cgi-bin" directory of your intranet. Following this tutorial, your server application will be called "tutorial" so you should use this name here - simply change "untitled" to "tutorial". "cgi-bin" is a standard directory name, "localhost", however, should be changed to the name of your intranet.

Note - In order to work out where to put your server on your filesystem, check the way your Web server has been configured with respect to the physical location of the "cgi-bin" area of the server.
  14. Press "Ok" in the Customize dialog.
    For this tutorial, we are going to use the default data handlers so we do not need to change them. Pressing "Ok" closes the dialog.
  15. Back in the Callbacks dialog, press the "Group" button and select "MyGroup" from the Group Editor.
    You can type the name of the group directly into the text box, but selecting it from the Group Editor avoids typing mistakes.
  16. Press "Add" to add your "doGoButton" function to the list of callbacks.
  17. Close the Callbacks dialog.
  18. Save your design as "tutorial.xd".
    It is good practice to save your design periodically.
  19. Display the Generate dialog by selecting "Generate" from the Generate menu.
  20. Choose "C" from the Language menu.
  21. Choose a target directory for your files.
  22. Make sure that the "Stubs", "Code", "Externs", "Main program" and "Makefile" generate toggles are set.
    The "Stubs" file is not selected by default, so make sure it is set before generating.
  23. Press the "Options" button at the bottom of the Generate dialog to display the Code Options dialog.
    Do not confuse this with the Primary Source File Options Dialog which is displayed when pressing the "Options" button next to the "Code" file.
  24. In the Code Options dialog, change the "Strings" option menu to "Code".
    By default, this is set to "Resources". For this simple tutorial, it is easier to generate the strings (which is all the labels you have set) into the code. This affects only the appearance of the final dialog.
  25. Press "Ok" in the Code Options dialog to save your change and dismiss the dialog.
  26. Back in the Generate dialog, press "Generate".
    As well as generating the main code files, Makefile and HTML index in the top-level directory, Sun WorkShop Visual also generates the following sub-directories:
  - callouts_c. This contains the client-side stubs for Smart Code callbacks.
  - server_c. This contains all the code for your server including the Smart Code callback stub.
  - groups_c. This contains the code for the Groups.
  - motif_c. This contains the "wrappers" which make Group components independent of Motif.
  - http_c. This contains all the code for communication between the client and the server using the HTTP protocol.
Figure 17-5 shows all the files generated. The files containing stubs are highlighted.

FIGURE  17-5 Files and Directories Generated For Tutorial

  27. Save your design.
    The rest of this stage of the tutorial takes place outside of Sun WorkShop Visual. You can exit Sun WorkShop Visual if you wish.
Of the generated files, there are three you need to know more about. These are:

callouts_c/doGoButton_cs.c. This file is in the client side of your application. It contains the "precondition" and "postcondition" routines which are called directly before and after the server callback is called. By default they are empty. You only need to fill them in if, for example, you wish to preprocess or postprocess the group structure being sent to the server.
callouts_c/std_cs.c. This file contains the standard error handler for handling out of band data. It also contains the routine which communicates with the server. It is this routine which calls the precondition and postcondition routines. Although this file is always the same, it is placed here so that, if necessary, you can see for yourself how the handshaking is performed. You would not normally have to change this file.
server_c/doGoButton.c. This file contains the Smart Code callback stub which will be called from the client. It is residing in the server application.
"Generated Code" section contains more information on the code generated by Sun WorkShop Visual for thin client and Internet Smart Code.

  28. Edit the file doGoButton.c in the "server_c" directory.
    This contains the Smart Code callback stub. You need to add code here to make the server perform its function.
  29. Change the method "doGoButton_callback" so that it contains the lines indicated below:

int
doGoButton ( sc_data_t * data)
{
		MyGroup_t * g = (MyGroup_t*)data->group;




        if (SC_GET(g->toggle1))
                SC_SET(g->text1, "Server says: toggle is set");
        else
                SC_SET(g->text1, "Server says: toggle is NOT set");





        return 1;
}
  30. Make sure you have the environment variable VISUROOT set to Sun WorkShop Visual's install directory and your C compiler is in your PATH.
    See the Generating Code chapter in the main User Guide for more information on setting up prior to compiling.
  31. At the command prompt, type
	make
    to build the client application and:
	make server
    to build the server application.
    You can take the entire "server_c" directory somewhere else to compile. Take a copy of the Makefile too. The Makefile assumes that the directory "server_c" is beneath it.
  32. Move the server application (named "tutorial" in the "server_c" directory) to the location named in the URL field, as in Sun WorkShop Visual Replay.
  33. Try running the client application (named "tutorial" in the generate directory).
Press the button both with and without the toggle set. A message is displayed in the text box. This message is produced by the server, which is checking the value of the toggle first. Although this is a simple example, it demonstrates a structure which can easily be expanded.


Going a Step Further

Having completed this tutorial, you may like to try some more advanced features of thin client and Internet Smart Code. Provided as part of your Sun WorkShop Visual package are HTML files containing instructions for running supplied Sun WorkShop Visual Replay scripts which run the tutorials for you. You simply watch it running and then examine the results. Open the following files in an HTML browser:

  1. $VISUROOT/lib/locale/<YourLocale>/sc/timex.html. This describes the "Server Push" tutorial, demonstrating how to create an application with automatic remote update.
  2. $VISUROOT/lib/locale/<YourLocale>/sc/parsex.html. This describes how to create an application which fetches a Web page and then parses it.

Note - VISUROOT is the install directory of your Sun WorkShop Visual and "YourLocale" is the name of the locale you are using.


Thin Client Server Callbacks

When you generate code from a design containing a "Thin Client" Smart Code callback, Sun WorkShop Visual divides the generated code into a thin client application containing all the user interface code and a server containing the Smart Code callback. This server is a CGI script and therefore uses the standards of the World Wide Web as its means of communication. The code for communicating between the client and the server, using HTTP, is generated too.

Figure 17-6 gives a diagram of the structure of the application Sun WorkShop Visual generates when "Thin Client" callbacks are defined. In addition to the Smart Code callback in the server, stubs are generated on the client side of the application to allow you to do any necessary operations immediately before and after data is sent to the server.

The Smart Code callback residing in the server has a handle to a Group. This is the Group specified when the callback was defined. The Group provides a means of passing data between the client and server and gives the server some access to the interface components.

FIGURE  17-6 Thin Client Callback Application Structure


Server Application

The server application generated by Sun WorkShop Visual when thin client Smart Code is requested, is a CGI script. This means that it is a program, which can be written in any language (or shell script), which is accessed by means of the HTTP standard. The URL of your server application is passed from the client application to your Web server which then launches your server application. Output from the server application is returned to the client. The server application is generated in the language you request in the Generate dialog.

If you do not have a running Web server, your client and server applications will not be able to communicate. The Internet Smart Code also assumes that you have a Web server up and running in order to access Web pages on the Internet. Contact your Sun WorkShop supplier for information about Sun's Web server products or visit Sun's Web page at http://www.sun.com. There are a number of freely available Web servers available on the Internet; you should be able to locate one with a quick Web search.


Customizing the Server Connection

Pressing the "Customize" button for "Thin Client" or "Internet" Smart Code styles in the Callbacks dialog displays the Customize dialog shown in Figure 17-7.

This dialog allows you to specify how data is sent to and received from the server. There are two main areas in this dialog:

  1. Connections. The details of the network connections, such as the proxy and the URL.
  2. Custom data handlers. The names of routines which should be used for communicating across the network instead of those supplied by Sun WorkShop Visual.
These are described in separate sections below.

FIGURE  17-7 Customize Dialog


Connections

Sun WorkShop Visual uses the information in this section to generate code to establish a link across a network. The fields in this dialog are:

  1. Proxy Host. This is only required if you are behind a firewall. It is the name of the conduit between your computer and the internet.
  2. Proxy Port. This is only required if you are behind a firewall. It is the port number to use on the proxy host.

Note - If you are not sure what values to set for proxies, see More on Proxies.
  3. URL. This is the only field in the dialog which must be filled in. It is a string which describes the location of an HTML document or CGI script. What this "document" is depends on the style of communication you have chosen (as described above):
If you have chosen thin client Smart Code, the URL probably names a CGI program which is the server side of your application.
If you have chosen Internet Smart Code but have not specified a Receive Handler, the URL is the name of a completely separate remote server from which you only expect some acknowledgment of receipt.
If you have chosen Internet Smart Code and you have specified a Receive Handler, the URL probably names a completely separate remote server (or file on that server) from which you are expecting data in a particular format.
URLs are part of the established World Wide Web protocol.

  4. Query Data. This is a query string. When a question mark (?) appears in a URL, the remainder is assumed to be an algorithm for matching a document or its contents, such as may be expected by a search engine. It is up to the server to interpret this string. Sun WorkShop Visual appends the question mark character and then the query string to the URL.
  5. Server Push. This is a toggle which, when selected, tells Sun WorkShop Visual that you are prepared to accept asynchronous input from the server. This means that data will be coming into the client application when it is ready rather than after a request.

URL Library

The URL library used by, and supplied with, Sun WorkShop Visual has been modeled on the Java URL and URLConnection classes in order to facilitate the transition to Java and to maintain a common interface whether you are using C, C++ or Java. This library is available for your use, should you wish to maintain full control over the connection between client and server. The programming interface for the URL library is described in the files reached from symbolic links inside the generated index.html file. This file is found in your generate directory, as described in HTML Files.

If you have not yet generated code, open the following file in a HTML browser:

$VISUROOT/lib/locale/<your_locale>/sc/URL.html

where VISUROOT is the install directory of your Sun WorkShop Visual and <your_locale> is the name of the locale you are using. If you are unsure about your locale, try typing locale into a terminal window. This prints out your locale information. Use the string assigned to LANG. Example locales are:

C (for English).
ja (for Japanese).

More on Proxies

A network proxy is a conduit linking your computer (or your Intranet) to the Internet through a firewall. A firewall is a "security screen" which prevents unauthorized access to your computer from the outside world. In order to connect to the internet from behind a firewall, you will have to specify a proxy host and a proxy port. If you don't already know what these are, you could try the following options:

  1. Ask your systems administrator. Someone must have configured your network, email and internet connection.
  2. Find out how your Web browser is configured because, in order to connect to the Internet, it also has to use a proxy. More about this in the following paragraph.
Somewhere in your Web browser, under "Options" or "Preferences" or "Configuration", there will be a dialog where you can specify your network preferences. This dialog allows you to tell the browser whether or not it needs to use a proxy and, if so, what it is. There are a number of options here:

  1. No proxy is used. In this case, you do not need to provide one in Sun WorkShop Visual's Customize dialog.
  2. A proxy is specified manually either in this dialog or a sub-dialog. If this is the case, use the proxy specified. If there is a choice of proxies, use the HTTP proxy.
  3. The URL of a configuration file is specified for automatic setting of the proxy. In this case, check the proxy specified in the configuration file.

Constant, Variable or Function

"Proxy Host", "Proxy Port", "URL" and "Query Data" each have a corresponding option menu allowing you to define whether the value you enter is a "Constant", "Variable" or "Function". As its name suggests, a constant simply retains the value typed. Selecting "Variable" causes Sun WorkShop Visual to declare an external variable with the specified name. You should define the variable in your own code.

Selecting "Function" causes Sun WorkShop Visual to generate a file in the "callouts" sub-directory using the name of the function as the filename. This file contains two functions: a "get" and a "set". These routines contain a commented spaceholder where you should insert your own code for getting and setting the proxy host.

For example, Figure 17-8 shows a proxy host defined as a function called "MyProxyHost". Assuming C code, Sun WorkShop Visual would generate the following two routines in the file named MyProxyHost.c:

static char * MyProxyHost_value = (char*)0;
char *
get_MyProxyHost ( AnyGroup_t* ingroup)
{
	group0_t * group = (group0_t*)ingroup;
	if (!MyProxyHost_value) {
		/* do something */
		(void) fprintf( stderr, "Warning: getMyProxyHost() 		
								returns NULL\n");
	}
	return MyProxyHost_value;
}




void
set_MyProxyHost (AnyGroup_t* ingroup, char* value)
{
	group0_t * group = (group0_t*)ingroup;
	/* set MyProxyHost_value here */
}
The comments indicate where you should add code to get and set the proxy host. You may, for example, have defined a form in your user interface which allows a user to enter a proxy host into a text field. You might then get the contents of the text field and assign it to the "MyProxyHost_value" shown above.

FIGURE  17-8 "MyProxyHost" as a Function

The bibliography lists books which you may find useful in connection with networking and protocols.


Custom Data Handlers

The section of the Customize dialog labelled "Custom Data Handlers" gives you the option of overriding the following default routines:

  1. Send. This is the routine which sends data to the server
  2. Receive. This is the routine which receives data from the server.
  3. Out of Band Data. This is the routine which handles data of an unexpected type returning from the server.
Leaving an empty text box for the Send or Receive handlers causes Sun WorkShop Visual to generate a default routine. For Out of Band Data, the name of the default routine appears in the text box. These defaults provide basic functionality, allowing you to create a working client-server application without immediately having to provide your own handlers. The following sub-sections describe briefly what the default routines give you as well as information to help you write your own.


Send Handler

By default, Sun WorkShop Visual generates a routine which sends data to the server. This routine does the following:

Opens a print stream to the server.
Prints the MIME header.
Prints each component of the group as a serialized HTTP object.
Prints the MIME end.
If you have specified a send handler in the Customize dialog, the routine described above will not be called. Instead, your routine is called. Your routine is defined as returning an integer. It takes two parameters, in the following order:

A pointer to the output stream.
A pointer to the group.
All of the communication protocol remains in place when you override the send routine - it is only the sending of data which is replaced. The default send routine is still generated, but not called, when you override it. If you wish to look at it to see how it sends the MIME header, MIME end and how it serializes the group components, it is called httpSendOutputStream and is found in:

<YourGenerateDirectory>/http_c/tr_http.c

Your send handler is placed in the callouts directory. See Generated Code for more details on the code generated and where it is located.

If you generate code from a design using the Get/Set shorthand notation described in Go Live, an example Send Handler is generated. You may wish to use this as a starting point.


Receive Handler

If you specify a receive data handler in the Customize dialog, this routine is called in addition to all of the communication protocol which Sun WorkShop Visual generates by default.

In C and C++ code, your routine is defined as returning an integer and taking two parameters:

  1. A pointer to a structure defined by Sun WorkShop Visual called sc_stdcs_t for C code and sc_stdcs_c for C++. This structure gives your routine access to the Group. There are also private fields which are for internal use only. It is defined in the file sc_groups_c.h in the directory where you are generating code.
  2. A pointer to a structure defined by Sun WorkShop Visual called sc_idata_t in C and sc_idata_c in C++. This structure gives your routine access to the input stream, its length and MIME type. It is defined in the file http_transport.h in the http sub-directory.
For Java, the Receive Handler you specify is made a subclass of the Sun WorkShop Visual defined class, SCInputDataHandler. Add your own code to the doit() method. This method is "void" and takes one parameter which is an instance of the SCIData class, as defined in SCIData.java in the utils_java sub-directory.

The receive handler supplied by default ignores the returned data. You will almost certainly wish to parse the returned data. Sun WorkShop Visual is supplied with a full HTML parser. This parser is simple to use because it is data driven - that is, in the same way that widgets register an interest in the callbacks they wish to see, you can tell the parser which HTML tags you are interested in. This is all explained in detail in Extracting Information from HTML Data.

Your receive handler is placed in the callouts directory. See Generated Code for more details on the code generated and where it is located.

If you generate code from a design using the Get/Set shorthand notation described in Go Live, an example Receive Handler is generated. You may wish to use this as a starting point.


Out of Band Data Handler

Sun WorkShop Visual expects incoming data to conform to the MIME standard. If unexpected data is received, a routine in the client side of the application, generated by Sun WorkShop Visual, is called. This default routine, called scHTTPReply, simply prints the incoming data onto standard output. It is generated for you (into the callouts subdirectory) if you have a thin client or Internet Smart Code callback defined. It is generated in the language requested in the Generate dialog. This is the routine in C code:

int
scHTTPReply ( csdata, data)
        sc_stdcs_t* csdata;
        sc_idata* data;
{
	extern DataInputStream * newDataInputStream();




	InputStream* i = (InputStream*)(*data->getInputStream)( data);
	DataInputStream *  d = newDataInputStream( i);
	char * s;




	printf("data from server:\n");
	if (!d)  {
		printf("no data\n");
		return 0;
	}
	while ((s = (*d->readLine)( d)) != (char*)0) {
		printf("%s\n", s);
	}
	(*d->delete)( d);




	printf("end data\n");
}
If you specify your own routine as the "Out of Band Data" handler in the Customize dialog, the routine is defined in the same way as the default. The parameters it takes are exactly the same as those listed for the Receive Handler, which is described above.

For Java code, the format of the "Out of Band Data" handler is exactly the same as the Receive Handler - it is a subclass of the Sun WorkShop Visual defined class, SCInputDataHandler. Add your own code to the doit() method.

Your "Out of Band Data" handler is placed in the callouts directory. See Generated Code for more details on the code generated and where it is located.


Going Live

The "Go Live!" toggle lets you turn the Sun WorkShop Visual dynamic display into a fully functional thin client interface. You can set the toggle for both thin client and Internet callbacks.

You must define and add the callback before the "Go Live!" toggle becomes enabled. For thin client Smart Code, the callback is the name of a routine in the server. For Internet Smart Code, it is the name of a callback in your client application.

Sun WorkShop Visual provides a shorthand getter or setter to allow you to create dynamic customization in the Customize dialog. This shorthand uses the convention of spreadsheet packages (the `@' sign) to indicate "the contents of...". For example, the following:

@text1
means "the contents of the widget named text1 in the specified Group". The specified Group is the one named in the callbacks dialog. This notation fetches the contents of a control when it is used in any of the "Connections" fields (URL and Proxies). When it is used in the Receive handler field, it is assumed that you wish to set the contents of text1 to the data received from the server.


Go Live Tutorial

The following example illustrates "Go Live!". It uses the World Wide Web to access a remote website and read a Web page. You will need to be running a Web server in order to complete this tutorial.

  1. Create the hierarchy shown in Figure 17-9. This is a shell->form->{button, textfield, text}.

FIGURE  17-9 Hierarchy for Go Live Example

  2. Create a Group, called Group0, containing the textfield and text widget, making the textfield private.
    This is shown in Figure 17-10.

FIGURE  17-10 The Group for the Go Live Example

  3. Display the Callbacks dialog for button1.
  4. Set up an Internet Smart Code callback called "doit", as shown in Figure 17-11.
    Don't add it yet as we need to customize it first.

FIGURE  17-11 The Server Callback for the Go Live Example

  5. Press the "Customize" button.
  6. In the Customize dialog, put the getter shorthand notation for the contents of widget text1 into the "URL" field, as shown in Figure 17-12.
    This shorthand notation is: "@text1".
  7. Put the shorthand notation for the widget text2 into the "Receive Handler" field, as shown in Figure 17-12.
    This shorthand is: "@text2".

FIGURE  17-12 The Customize Dialog for the Go Live Example

If you are behind a firewall, you will also have to set the Proxy fields. See More on Proxies for details.

  8. Press "Ok" to save your settings and close the Customize dialog.
  9. Back in the Callbacks dialog, set the "Go Live!" toggle.
  10. Add the new callback and close the Callbacks dialog.
  11. In the dynamic display's textfield (the one named "text1"), type the following URL:
    http://www.sun.com/workshop
  12. Press button1 in the dynamic display.
    The main page of the Website typed into the textfield is displayed in text2.
  13. Try other URLs in text1 and press button1 again.
    As long as you type a valid URL, text2 will display the HTML page to which the URL refers. For example, try typing the URL of your Intranet, if you have one.
This example connects to a real server dynamically from within Sun WorkShop Visual.


Generated Code

Code files providing toolkit-independent wrappers and the definitions of Group objects are generated when Smart Code is selected from the Callbacks dialog. More files are generated for "Thin Client" and "Internet" than for "Get/Set" because, in addition to the getters and setters for the Group, all the code for the communication with a server is generated and, in the case of "Thin Client", the server side of your application too.

Some of these files are in specially named directories which are created by Sun WorkShop Visual and which appear beneath the directory chosen in the Generate dialog. Other files appear in the chosen directory. Figure 17-5 on page 517 shows the files generated for the thin client Smart Code tutorial. This gives you an idea of the files and subdirectories that are generated.

Most importantly, all your callbacks or other routines which may need editing (such as Custom Data Handlers, pre- and post-processing routines, Extra Data functions etc.) are kept together so that you may find them easily. You do not need to change any other code files.

Exactly what is generated differs according to whether you have requested only "Get/Set" Smart Code for your callbacks or you have asked for "Thin Client" or "Internet". The code generated in each case is described below.


Groups

If you are using groups but not Smart Code, an array of widgets is defined in the primary source file.

Without Smart Code, however, only the files described in the main User's Guide "Generated Code" chapter are generated and no new directories are created.


Get/Set Generated Code

When generating code files, Sun WorkShop Visual uses an extension appropriate to the chosen language:

  1. .c for C code
  2. .cpp for C++ code
  3. .java for Java code
The following examples use ".c" simply as an illustration.

If you have selected the "Get/Set" style of Smart Code for one or more callback, the following files are generated into the directory specified at the top of the Callbacks dialog:

Makefile. This is a standard Sun WorkShop Visual-generated makefile which takes account of the new subdirectories.
sc_groups_c.h. This header file simply includes the appropriate header files from the relevant subdirectory. It also defines the sc_data_t data structure, a pointer to which is passed into Smart Code callbacks and data handlers.
untitled.c. This is the main source code file.
untitled.h. This is the main header file.
untitled_stubs.c. This is where your callback stubs are generated.
index.html. This is an HTML file which lists and briefly explains all of the generated files. Use this file (by opening it in a web browser or other HTML reader) to find your way around the files and subdirectories.
In addition, the following sub-directories are created:

callouts_c. This contains a file for each "Extra Data" defined for a group which is defined as a function.
groups_c. This directory contains a source, header and HTML file for each group you have defined. It also contains a more general header file.
motif_c. This contains the Motif "wrappers" for each component in your group(s). This directory also contains an HTML file for each group.

Note - The "c" at the end of each directory name shows that C was the language chosen for code generation. If another language is chosen this is replaced accordingly.

Where to Add Your Own Code for Get/Set

With "Get/Set" Smart Code, the following stubs files are generated:

<progname>_stubs.cpp (<progname>_stubs.c). This is the traditional stubs file containing any callbacks you have defined. The stubs in this file have a strong connection with the toolkit and do not have access to any Groups or Smart Code data. Add only toolkit-specific code here. This file is generated into the directory specified in the Generate dialog.
<callbackname>_user.cpp (<callbackname>_user.c). This appears in the "callouts" sub-directory. When using Get/Set Smart Code, this contains the main callback stub, also named <callbackname>_user. This callback is free of any toolkit-specific code.
Extra Data function files. This refers to the "Extra Data" area in the Group Editor. If you have added extra data and defined it to be "Function", a file is generated using the name of the extra data as the filename. Each such file contains two routines: get_<extradata> and set_<extradata> (where <extradata> is the name supplied by you in the Group Editor). For C++ and Java these routines are methods of a class defined using the name of the "Extra Data" function. Information on using these routines is given in Extra Data - Function.
Figure 16-10 on page 506 shows a graphical representation of the files generated for the "Get/Set" Smart Code tutorial.


Thin Client/Internet Generated Code

When you generate code from a design containing any Smart Code callbacks, all of the files and directories described in "Get/Set Generated Code" above are generated. In addition, the following directories are created by Sun WorkShop Visual:

http_c. This contains the source code for parsing the URL and for sending and receiving data using the HTTP protocol.
server_c. This is the server-side of your application.
The directory "server_c" contains all the files you need to build the server which will connect to the thin client application containing your user interface. The whole of this directory can be taken away to be built and run on a remote web server.

The Makefile in the top-level directory contains the rules for building both the client (your design) and the server. To build the client, you need only type:

	make
at the command line. To build the server, type:

	make server
at the command line.


Note - If you move the server code elsewhere, remember to take the Makefile too.

Where To Add Your Own Code for Thin Client/Internet

The following types of stub can be generated when you create a thin client or Internet Smart Code callback. Some of these are optional, depending on whether you have specified any routines in the Customize dialog and in the Group Editor:

Toolkit-dependent client callback
Toolkit-independent client callback
Server callback (for thin client Smart Code only)
Precondition and postcondition routines
Internet connection functions
Group Extra Data functions
These are described separately below.

See Custom Data Handlers for details on adding your own data handlers and Extra Data - Function for information on adding extra functions to the Group.


Toolkit-dependent Client Callbacks

The file which contains your traditional, toolkit-dependent client callbacks is:

untitled_stubs.c (or untitled_stubs.cpp for C++ code generation).
This is the callbacks file generated when any callback is defined, regardless of whether Smart Code is being used or not. When you define a thin client or Internet Smart Code callback, Sun WorkShop Visual automatically generates a client side callback in this file. This contains toolkit-dependent code. You should only add code here which uses the toolkit.


Toolkit-independent Client Callbacks

The file which contains your toolkit-independent client callbacks is:

<callback>_cs.c (or <callback>_cs.cpp for C++ code generation).
For each thin client or Internet Smart Code callback, a file is generated into the callouts subdirectory using the name of the callback as the filename with the addition of "_cs" (standing for client server). The file contains the callback routine (or method in the case of C++ and Java). This contains toolkit-independent code with access to the Group.


Server Callbacks

Your server callbacks are located in:

server_c. There is a source file in this sub-directory for each callback you have defined. The file is given the same name as the callback.

Internet Connection Functions

A file is generated for each of the "Connections" in the Customize dialog, if "Function" is selected. Each file contains a get_<connection> and set_<connection> routine. The file is generated into the "callouts" subdirectory, using the name of the function that you specify as the filename.

A file is also generated for any custom data handlers specified in the Customize dialog. The filename is the name you type into the Customize dialog.


Extra Data Functions

As described in Where to Add Your Own Code for Get/Set, stub routines are generated for any "Extra Data" functions defined in the Group Editor.

Figure 17-5 on page 517 shows a graphical representation of the files generated for the "Thin Client" Smart Code tutorial.


HTML Files

In order to help you locate callbacks and familiarize yourself with the files generated, Sun WorkShop Visual also generates a set of HTML files. The main one is:

index.html
and is found in the top-level directory (i.e. the directory named in the Callbacks dialog).

This file, when opened in a web browser (or anything else which can read HTML) lists the files generated along with a brief description of each, as shown in Figure 17-13.

FIGURE  17-13 index.html in Netscape

There are hypertext links to other files, also generated by Sun WorkShop Visual, which describe the code generated for each group and each Motif "wrapper".

This file also contains a link to the online reference material for Smart Code programming. You can view this reference material directly by opening the following file in an HTML browser:

$VISUROOT/lib/locale/<YourLocale>/sc/index.html

where VISUROOT is the install directory of your Sun WorkShop Visual and YourLocale is the locale you are using. If you are unsure about your locale, try typing locale into a terminal window. This prints out your locale information. Use the string assigned to LANG. Example locales are:

C (for English).
ja (for Japanese).



Previous Next Contents Generated Index Doc Set Home

Copyright © 2000 Sun Microsystems, Inc. & Imperial Software Technology Ltd. All Rights Reserved.