# Code Preludes

Preludes are code fragments which WorkShop Visual will insert for you into the generated code. Logically, these are roughly equivalent to a #include statement at the relevant portion of the generated code.

Code Preludes Dialog

On the left of the Code Prelude dialog, text representing generated code for the selected widget is displayed. This code is representative only, so that you can see where the preludes will be added. This is not the actual generated code.

This dialog contains two sections - one for C code (labelled "Code preludes") and one for C++ (labelled "Method preludes"). Within both sections of text are toggles allowing you to choose whether you wish to edit the various kinds of prelude. There are two kinds of code prelude which can be used with C: pre-create and pre-manage.

There are three kinds of method preludes for use with C++: public, private and protected. These relate to their access.

Clicking the arrow beside the prelude type (C code or method) folds the text window for that type.

Adding a Code Prelude

Selecting one of the toggles which appear in the representative text, allows you to edit that type of prelude. There are two ways of adding a code prelude:

- Editing the generated code
- Typing the code into the dialog

Use the "Edit in place" toggle to specify which of the above you wish to use. If the "Edit in place" toggle is set, the generated code is opened for you to add your code.

If the "Edit in place" toggle is not set, a large text widget appears on the right of the dialog. Enter your code here. You should type the pre-creation code exactly as if you were using a text editor to type any other code. This means that you should observe all the rules and conventions of the target language, including end of line markers, bracketing conventions etc.

Pre-create Preludes

Pre-create preludes are inserted into the code before the selected widget is created.

If the selected widget is not a Shell widget, the pre-creation prelude is inserted in the creation procedure for the widget's parent Shell and you can provide any code without restriction. Pre-creation preludes are commonly used to set resources which can only be set at widget creation time. Below is a segment of generated code showing where pre-create preludes are added:

    /* xdesigner: prelude for rowcol1: pre-create */
    	Enter pre-create code here
    /* pre-create ends. */
    rowcol1 = XmCreateRowColumn ( widget1, "rowcol1", al, ac );
    		...

If you had selected "Edit in place" and you are editing the generated code directly, make sure that your code is typed into the area surrounded by special comments. It is then preserved when you regenerate code. You must not alter or remove the special comments.

Shell Pre-create Prelude

The code preludes for a Shell differ slightly from those of other widgets. The pre-creation prelude is used to replace the function header for the Shell's creation procedure. You can then, if you wish, define extra parameters.

The generated body of the procedure refers to one or more variables, which, in the default procedure heading, are passed as parameters. While these variables must be in scope, you can choose to pass them as parameters or declare them as global variables. The following variables must be in scope:

Required for Application Shell widgets:

    Display *display;
    char *app_name;
    int app_argc;
    char **app_argv;

Required for Dialog Shell or Top level Shell widgets:

    Widget parent;

In C for UIL the following are also required:

    MrmHierarchy hierarchy_id;
    MrmCode *class;

If you do not provide a pre-create prelude for a Shell widget, the creation procedure name defaults to create_ with the compulsory parameters as the only parameters.

Note - If you provide a pre-create prelude for a Shell, the call of the creation procedure in the generated default main() program is unlikely to be correct.

Pre-manage Preludes

The pre-manage prelude appears slightly later than the pre-create prelude in the generated code - just before the widget's callbacks are added. One use of this prelude is to set up client data for the callbacks. Other uses include setting the value of a Text widget, filling a ScrollingList, adding buttons from a file, or any other dynamic initializations. Below is a segment of generated code showing where pre-create preludes appear:

    		...
    /* prelude for shell1: pre-manage */
    	Enter pre-manage code here
    /* pre-manage ends. */
    XtSetArg(al[ac], XmNallowShellResize, TRUE); ac++;
    XtSetArg(al[ac], XmNargc, app_argc); ac++;
    XtSetArg(al[ac], XmNargv, app_argv); ac++;
    		...

If you had selected "Edit in place" and you are editing the generated code directly, make sure that your code is typed into the area surrounded by special comments. It is then preserved when you regenerate code. You must not alter or remove the special comments.

Shell Pre-manage Prelude

A Shell's pre-manage prelude is inserted just after the local declarations in the procedure. Otherwise it is the same as for other widgets.

Using the Edit Mechanism

WorkShop Visual uses the Sun Workshop Edit Server when you edit the generated code file. The file is opened in a separate editing window at the appropriate place in the file for the selected prelude type. As you select other prelude types the insertion point moves around the file so that you are always at the correct place. If you try to regenerate the code file when there are unsaved changes in the Edit Server window, you will be prompted to save the changes first.

See also:

- Callbacks
- Code Generation
- Widget and Variable Names
- Generate dialog
- Search
- About WorkShop Visual