From First Principles

Causeway is a Gui development environment which lets you build reliable APL Gui applications faster than any other tool you can buy. This manual combines the tutorial and reference which were included with previous versions of the software.

Howto
How to Use this Tutorial
Intro
What is Causeway?
Visualising
Visualising APL Variables as GUI Objects
Events
Programming with Events

This release requires Dyalog APL 12 or above (Unicode or Classic edition). See Installation for details on what you need to include in your application workspace.

The CPro workspace is the property of Dyalog Ltd.


CPro Turorial and Reference: How to Use this Tutorial

How to Use this Tutorial

The object of this tutorial guide is to get you comfortable with the basic concepts of Causeway, and to teach you the skills needed to design and build effective Gui applications with Dyalog APL and CausewayPro. It assumes that you have access to the CProQA workspace which contains all the examples used in the Tutorial, as well as sample dialogues for all the supplied Causeway classes.

It is vital that you get a clear understanding of the concepts outlined in the first section: if you really take to heart the idea that a Gui control is simply the visible manifestation of some variable(s), and that Causeway will do what is needed to update it when any of those variables change, then you are well on the way to writing reliable Windows applications in less time than you would have believed possible.

Of course there is still a lot of learning to do, but once you have mastered the basics of the Designer you should be able to get the visual side of the application developed very efficiently. Then you need to start finding your way around the extensive library of classes which are supplied with the system. These range from the simple (and obvious) elements like edit fields and buttons, to quite complex objects (like the TreeView control) which have many built-in functions and are almost a programming environment in their own right.

The Application Tutorial section is intended to show you how you can hook together some very basic file functions with a simple but functional Gui front-end, to make a useful ‘contacts manager’ application. It carries on to illustrate tabbed dialogues and an approach to MDI subforms. You can cheerfully skip both these sections – come back to them when you need to do something similar! It also covers the possibility of integrating the RainPro charting software and the NewLeaf report generator into a Causeway application. Again you can skip both these sections if you have no interest in business graphics or reporting.

The final section of the Tutorial shows you how to take the class template and generate a completely new class (a currency-formatted number) which integrates seamlessly with the supplied class library.


CPro Turorial and Reference: What is Causeway?

What is Causeway?

Managing Complexity

Causeway exists because programming effective Gui applications is a tedious and error-prone activity. The name ‘Causeway’ started as a joke – a causeway is a safe path across a bog, so think of the Causeway utilities as one possible safe path across the Gui (pronounced “Gooey”). This user guide sets out to explain the problem, and then walks you through a series of tutorial examples which should lead to a good understanding of the art of Windows programming in APL.

The first thing to realise is that good Windows applications are an order of magnitude more complex than the equivalent applications on a mainframe or under DOS. The reason is that the user is given almost complete freedom, and can interact with virtually any of the visual components at any time. He/she might close the whole thing down, probably by accident, with one simple click of the mouse; there is the possibility of someone resizing your main form or attempting to drag it completely off screen; it is very likely that at least one user will have set their form background colour to deep purple; ... and so on. Causeway classes have a lot of built-in behaviour which will help your system to survive this kind of attack from innocent users.

The next most common source of problems is when applications ‘forget’ to redraw some field when the underlying data changes. On a mainframe it was easy – the user typed some stuff and hit <Enter> or a function key. You read any altered data, refreshed everything on the screen with the new values, and waited for the next <Enter>. Under Windows there may be many different ways a user could interact with your data – for example a chart could be affected by a change to the numbers, a new choice of chart type, or of course by the user opening a completely new data file. Add a few floating toolbars and right-button menus and the complexity can quickly multiply out of control.

Causeway is primarily designed to take this administrative load away from the application programmer. Computers are good at this sort of thing, so why not leave APL to keep track of what you changed, and what must be re-done in consequence? The basic idea is that every object you see on the screen is simply the visual manifestation of some APL expression; associated with the object is a list of any variables which it depends on. If any of these change, Causeway will ensure that all dependent objects get redrawn.

Pre-requisites

A Windows APL interpreter (Dyalog APL/W 8.2 or higher). A working knowledge of Windows design standards. Please buy and read some recent update of “The Windows Interface – an Application Design Guide” (Microsoft Press) if you are new to writing Windows applications.


CPro Turorial and Reference: Visualising APL Variables as GUI Objects

Visualising APL Variables as GUI Objects

Perhaps the simplest example of an APL expression with an obvious visual presence is a text vector in an edit field:

Here I have assigned a value to the variable name, and set it as the “data to watch” of a text edit field. Anything the user types into the field is reflected back into the variable as soon as he/she leaves the field, for example by hitting the <Tab> key or pressing the <Close> button with the mouse. In the example, I have added a <Flip> button which executes the APL fragment name←⌽name and the edit field is redrawn immediately when the variable is assigned.

You can experiment with the Causeway designer to produce this simple dialogue – load the workspace, and type:

name←'Adrian Smith'
Dbx 'dbx.flip'

Use the right mouse button for a menu of possible new objects, and choose Text objects>Text entry from the menu.

Set its caption as “Name”, and then use the right button to get a menu of properties for the text object. Choose Text to associate it with the correct variable:

We shall see later that there are more possibilities than just the plain variable name in the top-left field. The right-hand field lists all the dependencies, in this case just the variable itself. Simply tab across to it to have Causeway make the obvious guess and fill in the dependency for you. The gui object will now be automatically redrawn when any other object changes the variable called name. The two lower fields can usually be left to default – they show you what will happen when the user changes the data in the gui object and Causeway must update the underlying data with the new values. In this case the variable is simply assigned the field content (represented here as omega) and the change to the variable is notified so that any other gui objects which list ‘name’ in their dependencies will be redrawn.


CPro Turorial and Reference: Programming with Events

Programming with Events

The second interesting object on the dialog box was a button labelled <Flip> Clearly this must reverse name when pressed, and it must also notify Causeway so that dependencies can be checked.

This time, use the right button to add Buttons>Action Button, set its caption, and then select Behaviour from the right-mouse menu:

Now you can be an APL programmer again!

If you followed through the example, you will have noticed that you just produced a fully-functional Windows application without learning any new ⎕ functions! In fact you only entered one line of APL code:

name←⌽name

... which was a simple statement of the problem. You may also have noticed that the buttons made themselves at a good default size, and perhaps you took advantage of the 4-pixel ‘snap to grid’ to line them up nicely. As you work through the rest of this short tutorial introduction, you should keep looking back and thinking “How would I have done this without Causeway” and you will begin to add up the hours and days it can save you. When you finish a piece of work, look back on it and rate it for good looks, ease of use, and reliability. Of course it will not go quite as fast as the same application coded from the ground up in Dyalog, but if your users want something now, something that looks right, something that works and keeps on working, then Causeway is for you.


Exploring the Designer

This chapter takes you through the Causeway form designer. Read as much as you need to allow you to create and run a simple form.

  • How to Make a Simple Dialogue Box
  • Adding Controls
  • Arranging and Aligning Objects
  • Setting the Designer Preferences
  • Setting Properties
  • Changing an Object’s Type
  • Running the Finished Dialogue

Some time spent practising with the various alignment tools is likely to pay considerable dividends when you start designing real dialogues.


CPro Turorial and Reference: How to Make a Simple Dialogue Box

How to Make a Simple Dialogue Box

This section should get you to the point where you are comfortable with the Causeway designer, and know how to investigate the various classes of object provided. The objective is to produce a very simple dialogue such as:

... and associate it with some variables in the workspace.

Let’s start by setting up the data and calling the dialogue designer:

      name←'Adrian'
      addr←'Brook House' 'Gilling East' 'York'
      eyes←1
      ∆eyecolour←'Blue' 'Brown' 'Green'
      Dbx 'dbx.rec'       ⍝ Save result in dbx.rec

It makes a lot of sense to keep with a naming convention such as dbx_xx or dbx.xxx (if you have a namespace called dbx) for all your Gui forms. This makes it much easier to analyse them for unused classes (for example using dbx.enum) or to search the actions for APL code.

Your completed screen layout will be saved in dbx.rec, which is a conventional APL 5-column array that can be viewed comfortably from the session. The first four columns give the object type, caption, position and size in pixels, with the origin at the upper left corner of the screen. Any properties you set for the objects are recorded in column-5 as a two-column matrix of property-value pairs.

You can, of course, modify or copy this matrix using APL in the normal way.

Here is the designer, with its floating property browser, as you should see it:

Exploring the Designer Toolbars

The leftmost buttons exit the designer, either saving your layout or discarding any changes. You can use Ctrl+E to exit (and save), Ctrl+S to save without exiting, Ctrl+A to save with a new name, or Ctrl+Q to quit. The centre two buttons invoke the ‘Object Sorter’ (to arrange the tab-order of controls) and the designer’s ‘Preferences’ dialogue (to set object spacing and framing parameters).

The ! button is reserved for future use with the CPro ‘Class Wizard’ and the ? button offers online help for the selected object and is activated with the F1 key. Finally, you can press the last button or hit F5 to run your form.

The Attach Toggles

Below the position/size fields is a bank of six toggling buttons which control how the object is attached to the edges of the parent form or subform. In this example, a field is attached both to height and to width, so that it will maintain its margins whatever you do to the form size. When you add a new object, it always attaches to the left edge and the top of the parent form. Positive positions measure the distance from the left (top) of the form to the left (top) of the object; negative positions measure from the right (bottom) to the right (bottom) edge of the object – note how the numbers change as the attachment of the object is toggled. The hot keys Ctrl+LRWTBH can be used as accelerators to attach the current object Left, Right etc.

The Lower Toolbar

The leftmost tool will centre the object horizontally. The second and third set the heights and widths of all selected objects to match the ‘senior’ object (see below). The next tool duplicates all the selected objects, and the following two tools set all selected objects to line up to the left or top edge of the senior object respectively (see the notes on Aligning and Arranging Objects for the way to use these effectively). Finally, you can choose to frame or delete the selected controls. All these tools have hot keys – hold the mouse over the tool for a pop-up tip.

Note that the toolbar may be set to float on top of the form you are designing, so that you can work on full-screen forms with no problem – use the right-mouse button on the property-browser to switch it to ‘Ontop’.

Alternatively, you can roll the property box up out of the way with the button in the top right corner or <F8> which toggles the rolled-up state. All the properties are accessible from the right-mouse menu on each object, so you may find that this is a more comfortable way to work on a complex form. You find that the ‘menu’ key can be used to pop up the right-mouse menu, and that all the standard options now have hot-keys allocated on the menus.


CPro Turorial and Reference: Adding Controls

Adding Controls

Use the right mouse button on the parent form to add a new control with its top left corner at that point. Many objects (such as buttons) are made at a standard size, otherwise you will find that as you move the mouse you are stretching a line (or rectangle) over the form which shows you the extent of your new object. Click again to fix the opposite corner.

When you add the object, it is given a blank caption and the properties are set to those defined in its class table. It will also be selected automatically, so you can overtype the caption and tab round to the other properties quickly.

Many objects (such as OK buttons) have a default size, so in this case you simply release the mouse to add it to your form ...

Missed! Not a big problem, however, as the new object is automatically selected. Simply ‘walk’ it to the correct spot using the cursor arrows. Then you can do the same for the Cancel button, and it might be a good idea to press Run (or hit <F5>) to check them!

Here we see that the form has a default style, no title, and the Dyalog APL icon. These are all things we shall change shortly!

Note that <OK> is set as the default button ⍎ press either <OK> or <Cancel> to close the form and continue designing.

The next stage is to add a Text edit object (for the name), a Notepad (for the address) and a Radio Button group for the eye colour. The first two are found from the Text objects submenu, and the radio buttons are listed under Selectors. You will find that for these last two you get a stretchy box (with the top corner where the mouse was) which you can pull to shape – click again to fix the size.

Here is the finished design. Several of the objects have captions, which you simply enter on the property browser as you make them. Note that there is no need to click in its caption field – this gets focus automatically when you click on an object, so that it is ready for you to start typing. You can also page up and down the objects with the <PgUp> and <PgDn> keys – the selected object is easy to spot ... it is the one with the bright blue handles!

Experiment with the various anchoring options (try sticking the OK and Cancel buttons to the right with Ctrl+R) – stretch the form to check the effect.


CPro Turorial and Reference: Arranging and Aligning Objects

Arranging and Aligning Objects

Setting the Tab Order

Objects are saved in the order you define them, which can be a nuisance if you have several fields and want a sensible tab-sequence between them. You probably want the Name field first, followed by Address and Eye-colour. Here is the way they came out first time around:

If you use the ‘OS’ button to bring up the ‘Object Sorter’ window, you can move any object up/down the list so that fields are created in a convenient order – I have selected eyes here. This will also help the PgUp/PgDn buttons walk around the objects in a more reasonable way, so it is probably worth arranging all the objects on a complex form into a ‘top-down’ sequence just to make editing a little easier.

Selecting and Aligning Objects

When you drag a rectangle around several objects, all those you select will have solid-coloured handles, but only one is coloured bright cyan – this is the ‘senior’ object of the set and is the one to which the others will be aligned. By default it is the first in the tab-order, but if you want to align to a specific object, you can click this one first, then use Ctrl+Click to select the others one at a time. Here I am about to line up the Address field with the left edge of the Name:

Note that most of the controls in the property browser are greyed out when more than one object is selected, however you can still use the attach toggles to anchor a whole group of objects at the same time. You can also move all the selected objects as a unit – when you drag any of them you will find you are placing a rectangle drawn around the “bounding box” of all the selected objects. If you didn’t mean it, just drop them anywhere and hit Ctrl+Z to undo!

The way the align tools work depends on how the senior object is attached. If you press ‘align to sides’ and the senior object is attached to the right-hand side of the form, any other objects will move so that their right edges align with its right edge. They will also be given the same attachment. The same applies if you have attached the master object to width or height – in this case any other objects will be stretched to the same size and attached similarly.

Spacing and Distributing Objects

To have a set of objects aligned and spaced automatically, select them as above and Shift+Click the appropriate alignment tool – they will be aligned to the edge shown on the tool and spaced evenly in the other dimension using the ‘spacing’ value set in the Preferences dialogue.

Sometimes it is convenient to have a set of buttons or edit fields spread out evenly to occupy a fixed region of the form – in this case select them as above and Ctrl+Click the tool. The first and last controls stay in place and the remainder are evenly distributed between them.

Using the Clipboard

To copy a selection of controls between forms, either design them both together:

Dbx¨dbx.one dbx.two

... or just click back to the APL session and run Dbx again on the second form. Now you can use the standard Windows keys Ctrl+C to copy the selected objects and Ctrl+V to paste them into the other form. They will be pasted in the same position in the target form, unless this would put part of a pasted control outside the form, in which case they will be placed tight to the nearest edge.

Note that Ctrl+Z will undo the most recent change on whichever form has focus.


CPro Turorial and Reference: Setting the Designer Preferences

Setting the Designer Preferences

You can use this dialogue (accessed from the <PR> button on the top toolbar) to control the detailed behaviour of the alignment tools and to reduce the list of classes on the ‘New’ sub-menus to those appropriate to your system.

The ‘Alignment gap’ is used to space out the selected objects when you Shift-Click either of the two alignment tools (use 0 for buttons on a toolbar, 8 is a good number for vertically separating edit fields); the ‘Frame offset’ is specific to the ‘Frame’ tool. It determines how much space to leave as a border around the entire collection of framed tools.

Note that you can exclude the Windows-95 controls (such as the tree, listview, rich-text) from the set of available objects, and if you are designing a form which may be converted to HTML you can restrict your choice very severely to the simple controls which may be used in an HTML form.

If you use the right-mouse button on the property browser you can set it to stay on top (handy for laptop users designing large forms) and also control the ‘Snap to grid’ behaviour of controls as they are drawn, resized or moved.

You can start the object sorter from here, and also use this as a quick exit point if you have opened several forms at the same time.

All these preferences are saved for you in Causeway.ini (in the Windows directory) whenever you exit the designer.


CPro Turorial and Reference: Setting Properties

Setting Properties

When you click on any object on the form, the property browser automatically shows you the current value of all the properties of the object. You can tab around to change the numbers, and when you press <Enter> or leave any field, the object will be updated to match. The pull-down choices are updated immediately when you click on a new selection.

All objects have the Behaviour and Groups properties. You will find that the remaining buttons and fields vary depending on how the object has been specified in its class namespace. Click on the various objects on your form and tab around the properties to see what you can change.

The example shows a Spin Box which has a good mixture of property types. The style button opens a multi-select list where you can add generic styles to the objects. Buttons labelled in green set User properties (bi-directional APL expressions) and blue buttons are Runtime properties (any APL expressions). When you come to design your own classes, you will find that user-defined property types are also represented as simple buttons, which call your own property-maintenance functions.

Text and numeric properties (such as ‘Hint’ and ‘Delay’) are simply entered in the fields – you will find that any numeric fields have built-in spin behaviour on the up and down arrow keys. If the text is too long for the space provided, just use the ‘...’ button to bring up a small notepad.

Boolean and ‘OneOf’ properties can be selected from a dropdown, and any ‘ManyOf’ properties will be shown as a button which invokes a pop-up multiple selection.

As you assign non-default values to the various properties, the adjacent labels are changed to red, and where possible, the button captions are also updated to reflect the new values. Here is the same object with some properties set:

Here you can see that two styles have been selected, the control is watching variable ∆count, and it is stepping in 10s.

The delay before first repeat is left to default, but it is spinning faster and tracking has been turned off to prevent other controls which depend on this variable updating as the control spins. The labels adjacent to all the non-default properties are red ⍎ these are the only values which will be saved in the dialogue-box definition.

Setting common properties on several objects

In this example, a simple text-edit box has been selected in addition to the spin box. You will see that only those properties in common between the two objects are now available to be changed. Any changes made will be set for all the selected objects. This gives you a quick way of replicating some properties across several objects, for example the typeface or colour on more than one label at at time.

Copying specific properties between objects

When you select Copy,Properties from the right-mouse menu you are allowed to select only those properties which you want to propagate to other objects. You can then use Edit,Paste to set these properties in one or more other objects, depending what is selected.

Send comments on this topic
© Dyalog Ltd 2008


CPro Turorial and Reference: Data to Watch

Data to Watch

Each object you add to your base form (except for trivial things like <OK> buttons) can watch and possibly update one or more APL variables. For example, a Text Edit object would normally watch a simple text vector. Any changes you made to the visible field on the screen would be reflected back into your variable as soon as the user left the field (with the Tab key or by pressing a button on the form).

Runtime and User Properties

Almost all objects make use of these property types, which are shown on the property browser as buttons with blue or green labels. The designer picks up the prompt from the object definition, so you usually have some idea what the object expects to see here! When the object can modify data in some way (e.g. a Scrolling List can change the selection) this is the variable that gets changed. Here is a simple example where a text field updates a value indexed from a vector of text vectors:

The expression may be a simple variable name, or any expression which is valid to the left of an assignment. You should imagine wrapping a pair of parentheses around the data expression and adding an assignment arrow like this:

(name)←
(inx⊃names)←
(msk/names)←
(names[inx])←
('Your name is ',name)←

... this is what Causeway will do to get the user∇s changes reflected back to your data. Essentially anything involving indexing is fine, as are all valid selective specifications. The last example is fine for a label, but will fail on a SYNTAX ERROR if the user touches it in a text field. To help you see what is going on here, the lower field shows you the reversed expression that will be used. You can even modify this if you need to, using ⍵ as illustrated to act as a placeholder for the data that will be read from the control.

Note that you may double-click on any variable (or function) name mentioned in this field to open an edit window on the object.

Dependencies (Refresh on a Change to) ...

The object must refresh its display when any variables named in this list change, or when the name is broadcast by an entry in the ‘Event-Action’ table following the execution of some APL code. The name is often just a repeat of the primary data, but remember that this can be any APL expression, so you always need to specify it explicitly. If you simply tab into this field, the Designer will take a reasonable guess and fill it in for you.

In our example, we could illustrate the effect by running up the finished form:

#.CPro.Make dbx.rec     ⍝ Start the form running
eyes←2                  ⍝ Change some data
#.CPro.Notify 'eyes'    ⍝ Tell Causeway

Of course another way would be to make several copies of the form ...

#.CPro.Make ¨3⍴⊂dbx_rec ⍝ Start 3 copies

... change the data on any one and the other two should immediately change to match. Of course you will have to move the forms so that you can see them all at the same time.

Note that this need not be the name of a real variable. If you holler ‘hi’ from an action, all the fields which watch for a change to ‘hi’ get refreshed regardless of what they are displaying – this can be a useful shortcut to getting everything redone after a <Recalc> operation.

Forcing Causeway to Redraw the Control

To save time (and reduce screen flicker), Causeway will avoid redrawing controls if the data expression evaluates to exactly the same value as it did the last time the control was refreshed. This means that Causeway will buffer the old value and compare it with the new value every time a refresh is required – it may sometimes be better just to accept the redraw, thus saving on workspace. Also there are times when you want to force a redraw, for example if you are using unnamed graphic objects.

To prevent Causeway making the comparison with the previous value, check the ‘Always refresh ...’ box below the data expression.

Pre-Refresh, Validation and Post-Update Events

There are three places where your application code can step in during the automatic processing sequence which CPro runs for every control on a form.

  • Just before the expression in the ‘Data to Watch’ dialogue is evaluated
  • After the user has made a change to the control, but before the expression has been reversed and re-executed
  • After the expression has been re-executed and the data has been returned to the watched variable.

Pre-Refresh Processing

This is most often used to run some application code which collects data into a format suitable for a specialised control. For example a Tree Control requires a two-column matrix of items and levels – you may store your data in a parent-child structure which requires reformatting before it is suitable. In this case you might set the watched variable as (say) datatree and your pre-refresh code would look like:

PR :  : datatree←#.MakeTree ∆parent ∆child  :

Note that CPro will always run the Pre-Refresh actions, but you can prevent the actual data-expression from executing by specifying ∇Reject here. If the result of executing the data expression matches the previous field content, CPro will normally skip the redraw to save time and flicker. Very occasionally you need to force the refresh (typically for a chart where the PostScript definition may be unchanged but the window size may have changed) – you can over-ride the CPro caching by checking the ‘Forced refresh’ box under the expression definition.

Validating Data

This is catered for by a special Validate event which is triggered after your data has been read from the object, but before it is assigned back into the associated variable. The data is available for inspection as ⍵ (omega), and there are two possibilities here. You can modify the data in passing:

VL: :⍵←0⌈99⌊⍵   ⍝ Force range

... or you can check it and reject the event if it fails:

VL: ⍵<100 : ∇Reject ⍝ Bounce if >99

In the latter case, no assignment takes place, the variable name is not notified (so no other dependent controls will be updated), and the object is immediately refreshed with the original value.

Post-Update Processing

This may be used to trigger ‘knock-on’ processing, such as a background database update, or simply to reverse the effect of a pre-refresh by disassembling the data returned from the control into a more application-friendly format:

PU :  :  (∆parent ∆child)←#.ParseTree datatree  :

N.B. The Post-Update only runs after the user has changed the data. When the control is updated by CPro, only the PreRefresh event will be fired. You can use ‘Refresh Completed’ in the main table of object behaviours if you need to do additional processing here.


CPro Turorial and Reference: Object Behaviour - the Event-Action Table

Object Behaviour – the Event-Action Table

In Windows, this is where the action is! The most fundamental conceptual change you need to make when you first move from a mainframe or DOS-based environment is from a procedural approach to an event-based view of programming. The Event-Action table is where the vast majority of your APL code is called from.

It has four columns, specifying:

  • Event Name ... the drop-down lists these for you (double-click or Alt+Down opens the list)
  • APL Condition ... defaults to ‘true’ if omitted
  • APL Expression ... APL code to execute when condition is true
  • Name to Holler ... variables which must be refreshed

In the Event Name column you may use the familiar ‘short codes’ from Causeway shareware (such as DC for Double-Click), the full Dyalog event name (such as ‘Select’) or the event number, e.g. 40 would be the same as ‘GF’ or ‘GotFocus’. Use the numbers to handle custom events like 3005 which your application may queue on the object.

Note that you can execute more than one APL expression on any given event by entering several lines in the table – the event code will repeat downwards automatically against any non-blank entries. You can either use this to avoid diamonds (by listing several expressions against the same event) or to write ‘rule-based’ code where you use the condition to check for the state of some variable and fire code accordingly. For any particular event, the lines in the table execute in the order they appear in the table.

Use the right-mouse button over the row numbers to insert new rows, or to copy/move existing rows. You can also use the right-mouse over the column titles to sort the table by event code.

Running Code when Events Occur

If the condition evaluates to anything other than zero, the corresponding code will run, for example

SL: ⍴vec : Analyse vec

will execute Analyse vec for the non-empty case.

The simplest case is probably an Action Button, for example to select all the data in a scrolling list, you might find:

SL: :sel←⍳1↑⍴∆data : sel

When a Select event occurs on the button, your APL fragment runs, updating the variable sel (very likely a local variable on the form – see Locals) and hollering its name. Assuming you have set the list to refresh on a change to this variable, it will immediately select all the rows it is displaying.

Accessing the Event Argument</h3

Supposing you want to track the mouse position on a Backcloth, perhaps to put up extra information about the cell under the pointer. You clearly need to get at the event message, and this is provided for you as ⍵ (omega). You might write an action such as:

MM: :posn←⍵[1 2] ⍝ Record mouse row/col:posn

Similarly, to register the name of a dropped object (say a label was thrown into the wastebasket):

DD: :Delete_object 1⊃⍵

Accessing the Object Name

The name of the object which received the event is always available to you as ⍺ (alpha), for example to set a label to show today’s date on creation:

CR: :⍺ ∇Do 'Caption' (#.cal_disp ⎕TS)

Note the use of ∇ (del) as a shortcode for #.CPro. in the code shown above. This is optional, but has the advantage that if you relocate or rename the CPro namespace (for example to ⎕SE) you will not need to change any application code to have the new location substituted correctly.

If you will need to run lots of commands against an object, it is often handy to catch its internal name when it is created, and keep this as a local variable on the form:

CR: :pbar←⍺  ⍝ record name of progress bar

Rejecting Events

Of course, not all events can be rejected! The kind of things you could reject would be keystrokes in an edit field, say to allow only the characters ‘01(234) 56-789’ in a telephone number:

KP:~(3⊃⍵)∊'()- 0123456789': ∇Reject

You may call #.CPro.Reject to reject the event – the default is always to accept it. Another common use would be to reject a user’s request to close the main application (accidents can happen) if the return from a #.Win.Ask is 0, indicating <No> was pressed:

CL: 0=#.Win.Ask 'OK to quit application?' : #.CPro.Reject

Note that you put this action on a special ‘Close Request‘ event, not against ‘Destroy’ – this is to allow you to attach a different set of actions to a Destroy, to be run when the form is definitely closing.

Note that if you reject an event, none of the names in the ‘Notify’ column will be broadcast, and processing of the event table stops at this point.

Editing Functions and Variables from this Table

Note that you may double-click on any variable (or function) name mentioned in the condition or action columns to open an edit window on the object. If you try to open the editor on a non-existent object the designer will offer you the choice of a Function or a vector of text vectors. You can also press <F2> as an alternative to double-clicking on the name.


CPro Turorial and Reference: Changing an Object's Type

Changing an Object’s Type

You will sometimes find that you want to keep some of the current properties for an object, but have it appear differently in the form, for example it might be convenient to have a numeric field change to a spin box, but retain all other properties.

You can do this from the right-mouse menu on the object, which offers you all the alternative objects from the same group. For example to change an Action Button into a Tool Button (which expects a bitmap rather than a text caption):

The object will retain all the properties which are common to the old and new types, although you will find that the designer does not throw away the ‘dead’ properties until you exit. This allows you to experiment, for example to switch a Radio-group to a List-box, and switch back again without losing any of the properties along the way.

N.B. To change the type of a form, use the ‘Change Type‘ submenu in the same way, but you will find this under ‘Edit’ on the right mouse menu. This might be used to redefine a stand-alone form as an MDI child or incorporate it into a tabbed dialogue.


CPro Turorial and Reference: Running the Finished Dialogue

Running the Finished Dialogue

When you press the right-most button on the top toolbar (or hit F5) the designer calls #.CPro.Make to run the dialogue in its finished form. This will create the form and all the controls, and then attempt to run the expressions to generate the Runtime and User properties for each control, starting with the form and continuing with each control in the order they appear on the form. It is very likely that some of the expressions with fail on VALUE ERRORs or SYNTAX ERRORs as you may not have set up your test data yet, or you may simply have typed the APL code incorrectly. You will see something like this in the APL session:

      Dbx 'qw'
Designing qw
VALUE ERROR
Exec1[30] 13 'Text'#.CPro.RefreshWith txt
                                     ^

Here I set ‘txt’ as the Text property of a text edit field, but I have not yet created the variable. All I need to do to fix the problem is:

      txt←'Hi'
      →⎕LC

... and the form will appear. If you cannot easily fix the problem with a field, just use →⎕LC+1 to skip the expression and carry on to the next field. If you want to abort the test, just hit → and you will be able to continue in the designer with no damage done.

Setting Causeway to Skip Errors Automatically

By default, CPro does no error-trapping of application code, so that expressions fail as normal and APL waits for you to fix the problem. If you just want to see how a dialogue looks, an easy alternative is to skip errors automatically with:

    #.CPro.⍙debug←0
    Dbx 'qw'
Designing qw
VALUE ERROR
Exec1[30] 16 'Text'#.CPro.RefreshWith txt
                                     ^
Expression skipped, execution continues ...

All the errors are reported to the session but the finished form will come up on the screen for you to see. You can close it, and fix the errors one by one in the Designer, using the session log as a guide. In the example above, just click on the session (the Designer is non-modal to allow this) and assign a value to txt. Be sure to reset to #.CPro.⍙debug←1 before you do any serious application testing.

Note that you can set the form running with F5, move the running copy to one side, carry on designing and run it again, and so on. This could be a useful way of comparing alternative versions, as well as checking that the dependency mechanism is working correctly..

Running from the APL Session

When testing a dialogue, it is often more convenient to save it from the designer and use #.CPro.Make to run it from the APL session. A handy time-saver is to use function assignment:

      Dbx 'qw'
Designing qw
Dialogue design qw updated
Designer namespace cleared
      cm←#.CPro.Make
      cm qw

You will be able to test out the actions from any of the fields or buttons, and debug the attached APL code without having the screen cluttered with the designer toolbars etc.

One final thing to note is the difference between #.CPro.Make and #.CPro.Call for the finished dialogue.

#.CPro.Make dbx.rec           ⍝ returns to APL immediately
result←#.CPro.Call dbx.rec    ⍝ waits for the user to end

In general, if a dialogue needs OK/Cancel behaviour, you should #.CPro.Call it and check the result. You will get zero back for Cancel, 1 for OK. If a dialogue can be left open while the user carries on with other tasks, give it a Close button and #.CPro.Make it instead. However any changes it makes will generally go direct to global data, so (short of adding some complex Undo behaviour) there is no way for the user to back out.


Picture Strip Editor

This chapter covers the editor for drawing bitmap strips suitable for tool buttons and other imagelists.

  • Introducing the Picture Editor
  • Using the Editing Controls
  • Exporting and Importing Pictures
  • Working with the Finished Artwork

This also allows you to copy and modify any of the standard bitmaps (copy, paste etc) or import saved artwork from file.


CPro Turorial and Reference: Introducing the Picture Editor

Introducing the Picture Editor

The Picture Strip editor is an unsupported, but useful, namespace written and copyrighted by Richard Smith. It allows easy editing and manipulation of bitmap artwork suitable for any Imagelist (used in the ListView and TreeView controls) and for the new-style tool controls.

It is best suited to strips of quite small bitmaps (16 by 16 are ideal) but will work acceptably on any size up to around 40 by 40. There is no limit on the number of bitmaps in the strip.

It also allows you to make use of the standard Windows images from COMCTL.DLL or to import existing bitmaps from file.

It is shipped with the CPROQA workspace, but has no dependencies on Causeway, so you might like to run it from ⎕SE, or from a separate workspace.

Starting the Picture Editor

If you start the picture editor with an undefined name, it defaults to creating a plain grey 16 by 16 artwork for you:

Strip.Design'new'

To begin with a different size, simply pre-assign a suitable array:

pix←19 38⍴8
Strip.Design'pix'

Below is a 3-frame bitmap strip, where two frames have been copied from the standard tools, and the one in picture (image index=2) has been drawn using the editor:

Drawing on the current frame

Experiment with the drawing palette – you should find that it works more or less as you expect. You can choose colours for either mouse button, then clicking or dragging the mouse over the frame paints the appropriate pixels. To fill an enclosed region with the selected colour, hold <Ctrl> and click either button. If you intend to use the picture strip in a ListView or TreeView you should choose a suitable colour to indicate transparency – light grey is the default and is usually adequate. This colour may be set as the ‘SeeThru’ property of the ImageList; many people choose 13 (bright pink) here, as it is not often required in the artwork itself.

Moving between pictures

This bank of 5 buttons scrolls through the pictures – the one in the middle is always the frame you are working on. The neighbouring pictures are always shown on the buttons to left and right so you can see how the overall image strip will appear in your toolbar.

Adding, removing and shuffling pictures

This bank of 3 buttons allows you to add a new blank picture or make a copy of the current frame (Insert will put it in front of the current picture, Append and Replicate put it after).

You can use <Del> to take the picture out of the strip and <Clear> to wipe it (to light grey) so you can start again.

These buttons move the current picture along the strip in either direction. In general it is best to have the pictures in the strip in the same sequence as the buttons on the toolbar. You can use the ImageIndex property of the Toolbutton to override this if you like, but it is very easy to get extremely confused if you do this.

Exiting from the picture editor

Press <Save> to save your changes and exit, or <Cancel> to leave the bits array as it was.

Opening up an existing strip

To start editing at a particular image, pass the image index as the optional left argument:

6 Strip.Design'pix'

To move quickly to an image index, use F5 which will prompt you for the number, then go to it.


CPro Turorial and Reference: Using the Editing Controls

Using the Editing Controls

You will notice that the picture drawing region is bordered on the left and above with three banks of small squares, coloured red, green and blue. With a little practice, these give an extremely powerful way of manipulating the image – particularly if it involves simple geometric shapes.

Manipulating the image

The red squares delete the corresponding row or column and move remaining pixels up or left respectively. The green squares insert a row or column in the default colour (grey), and the blue squares replicate the row or column. Both the green and blue squares push the remaining cells down or right, with the last row or column falling off the edge.

Using these controls, it is very easy to centre an image (just add or remove rows or columns) or make a shape fatter or thinner.


CPro Turorial and Reference: Exporting and Importing Pictures

Exporting and Importing Pictures

You can save the selected frame to file by filling in the required file name on the ‘Export’ tab.

You can replace the selected frame with a bitmap file by filling in the required file name on the ‘Import’ tab. This tab also allows you to copy any of the standard Windows pictures (just press the appropriate button to replace the selected frame) or to grab the entire set of standard pictures with the ‘Grab Toolbar’ button. This can often be a good starting point for your own toolbars – simply take the standard set, delete the ones you don’t need and insert any new tools which are specific to your application.

Send comments on this topic
© Dyalog Ltd 2008


CPro Turorial and Reference: Working with the Finished Artwork

Working with the Finished Artwork

The picture strip is saved in the workspace as a simple numeric matrix, giving indices into the standard 16-colour map. It can be set as the ‘Icons’ property of an ImageList object, as an alternative to providing a list of icon file names. If you intend to use the imagelist to make the icons in a TreeView or ListView, it is a good idea to specify ‘masked’ images here to get the appropriate transparent effect. You will need 2 completely separate sets of artwork to make the large and small icon sets, assuming you enable the ‘Icon’ view option in the ListView (Tree controls only need a single set of small icons).

Add the necessary imagelist objects to your form, and if necessary use the object sorter in the Designer to get them to the top of the list. A handy trick is to give each imagelist a local name on creation, for example

CR : small←⍺

then you can set these on creation of any ListView or TreeView objects which use them:

CR : ⍺ ∇Do 'SetImage' large small

To use the picture strip in a new-style toolbar (the ToolControl object), simply set it as the value of the ‘Artwork’ property. Currently, transparency is not supported here, so be sure to use light grey as the background colour. This will be mapped automatically to the Windows ‘button face’ colour so the bitmaps will blend correctly with the buttons. Each button in the toolbar will pick up the appropriate bitmap, although you can over-ride the sequence if you re-order the buttons and do not want to shuffle the pictures in the list.


Windows Utilities

Causeway is shipped with a collection of simple Windows utilities which have proved useful over the years.

  • Introduction to the Windows Utilities
  • Win.Ask – simple confirmation dialogue
  • Win.Color – call standard colour selection
  • Win.Fbx – standard file dialogue
  • Win.Find – list searching
  • Win.Folder – browse for folder
  • Win.Help – calling a help file
  • Win.HTMHelp – call into a CHM file at a given page
  • Win.Input – prompted user input
  • Win.Msg – information messages
  • Win.Pick – select one item from a list
  • Win.Popup – simple popup menu
  • Win.PopupTree – deep menu
  • Win.WhatsThis – “What’s This” help
  • Win.Ync – Yes/No/Cancel dialogue
  • Progress Bar Namespace

These have no dependencies on each other or on CPro, so you can selectively copy and use them as you wish.


CPro Turorial and Reference: Introduction to the Windows Utilities

Introduction to the Windows Utilities

The windows utilities shipped with CausewayPro are in the namespaces:

  • #.Win – simple stand-alone functions, covering:
    • Ask – Yes/No confirmation
    • Color – colour chooser
    • Fbx – file chooser
    • Find – phrase search in list
    • Folder – browse for folder
    • Help – invoke help file
    • HTMHelp – invoke CHM-style help
    • Input – prompt for text
    • Msg – display a message
    • Pick – select an item from a list
    • Popup – simple right-mouse menu
    • PopupTree – deep popup menu
    • WhatsThis – dialogue-box help
    • Ync – Yes/No/Cancel dialogue
  • #.GuiPbar – stand-alone progress bar

You can use these in combination with standard Causeway forms, or as simple utilities in your own Gui code.


CPro Turorial and Reference: Win.Ask – simple confirmation dialogue

Win.Ask – simple confirmation dialogue

ok←Win.Ask 'Are you sure?'

Generates a standard ‘Yes/No’ message-box, with the default button set to ‘No’ for safety. You can pass 1 as the optional left argument to set the default to ‘Yes’

Returns scalar 0 for ‘No’ or 1 for ‘Yes’ regardless of index origin.


CPro Turorial and Reference: Win.Color – call standard colour selection

Win.Color – call standard colour selection

To invoke the standard Windows colour dialogue with a given colour preselected:

rgb←Win.Color 128 0 0

This always returns a 3-element vector of RGB values. Pressing <Cancel> in the dialogue will return the old values.


CPro Turorial and Reference: Win.Fbx – standard file dialogue

Win.Fbx – standard file dialogue

This function is a very simple cover on the standard ‘FileBox’ dialogue call. You may want to update it to suit your own needs.

To look for a specific file type in the default directory (typically My Documents):

file←Win.Fbx '*.bmp'

This will add ‘*.*’ ‘All files’ as the first element of the selection dropdown, but will preselect the file type you pass. If you want to add more information for the user here:

file← Win.Fbx '*.zap' 'Zappo files'

Finally, you can set the directory to look in as the third argument:

Win.Fbx '*.bmp' 'Picture files'  'd:\temp'

To allow the user a choice of file types, you may nest the first two lists:

 Win.Fbx ('*.htm;*.html' '*.txt')('Web pages' 'Text files') 'c:\temp'

This returns null if the user presses <Cancel> otherwise the result is always the fully qualified upper-case filename. You may want to strip the directory portion from this and store just the relative path to the file. If the user does not supply an extension, the returned name will be qualified with the extension from the chosen file list. In the last example, this will be ‘.htm’ or ‘.txt’ depending on the chosen selection of files.


CPro Turorial and Reference: Win.Find – list searching

Win.Find – list searching

This dialogue is useful if you have a long list of codes and descriptions, and want a progressive search through the list. It is a very simple cover on the Windows ‘Combo’ control and can easily be adapted and improved:

pos←'Product Locator' Win.Find 0 ('L',°⍕¨1000+⍳1234)

The list will skip to the best available match. If no code matches, or the user presses <Cancel> it will return 0, otherwise it will return the position in the list in origin-1.


CPro Turorial and Reference: Win.Folder – browse for folder

Win.Folder – browse for folder

This is a simple cover for the BrowseBox object (Dyalog 9 and higher).

'd:\' Win.Folder 'Looking for a folder',⎕av[3],'to store your data in.'

The left argument is optional – the search will open in My Documents if nothing is given here. Note that you can have multi-line messages to give the user more information about the purpose of the search.


CPro Turorial and Reference: Win.Help – calling a help file

Win.Help – calling a help file

To invoke a standard help file at its contents page:

Win.Help'C:\APL\CAUSEWAY\Cpro.hlp'

You may also pass a context number as the left argument:

8020 Win.Help'C:\APL\CAUSEWAY\Cpro.hlp'

This will enter the help file directly at the page with this number. In the example, it will show the help for the CPro.Accel function. If you have built your help file with the 32-bit style ‘tree of books’ interface, it will have a matching *.CNT file associated with it. Pass ¯1 as the context number to open the file here.

Finally, you can pass a keyword, which will either go directly to the page (if the keyword is unique) or put up the built-in search dialogue to offer the user a choice of possible topics:

'Accelerators' Win.Help'C:\APL\CAUSEWAY\Cpro.hlp'

Here you can see the three topics which were marked with the given keyword.


CPro Turorial and Reference: Win.HTMHelp – call into a CHM file at a given page

Win.HTMHelp – call into a CHM file at a given page

This function provides basic support for calling CHM-style help files (compiled HTML files). It requires HHCtrl.OCX to be present on the user’s computer. The left argument (optional) gives the name of the html page to be invoked:

'quotes.htm' HTMHelp 'mychm.chm'

Files compiled with Causeway HelpStuf may fake the context number with the generated filename, which allows:

20 HTMHelp 'mychm.chm'

This will open the file at the topic with context# 20.

71 HTMHelp 'D:\Products\Common\cprohlp\cpro'

This will open the CPro documentation at this page, which has been compiled as t71.htm in the CHM.


CPro Turorial and Reference: Win.Input – prompted user input

Win.Input – prompted user input

This is a modernised version of the classic ‘QuoteQuad’ cover which was probably the first utility any APLer used to write in the days of typewriter terminals. However it still has its uses:

name←Win.Input 'Please enter your name ...'
name←name Win.Input 'Please enter your name ...'

The optional left argument is the current value of the string. This will be returned unchanged if the user presses <Cancel>. Note the interesting alternative syntax:

name←'Fred'
name Win.Input←'Please enter your name ...'


CPro Turorial and Reference: Win.Msg – information messages

Win.Msg – information messages

To call the standard Windows messagebox, in a variety of styles:

Win.Msg 'Print Complete'

The default is the ‘Info’ style, which just has a single <OK> button and the friendly bubble icon. Other options are:

  • ‘Warn’ – warning icon and ‘OK’ or ‘Cancel’ allowed
  • ‘Query’ – question icon and ‘Yes’ or ‘No allowed
  • ‘Error’ – red screw icon and ‘OK’ or ‘Cancel’ allowed
  • ‘File’ – red screw icon and ‘Retry’ or ‘Cancel’ allowed
  • ‘System’ – red screw icon and ‘OK’ only allowed

For example:

'File' Win.Msg 'Problem reading your data'

You may like to adapt this function, adding in more button selections as required.


CPro Turorial and Reference: Win.Pick – select one item from a list

Win.Pick – select one item from a list

To choose a single item from a long list of options:

'Choose one' Win.Pick 2 ('Fat' 'Cat' )

The left argument gives the dialogue box title, the right argument is a 2-element vector giving the current choice and the list as a vector of text vectors.

If you pass a matrix as the list element, the function uses a fixed-pitch font for the listbox on the assumption that you wish to display a formatted matrix with embedded blanks.


CPro Turorial and Reference: Win.Popup – simple popup menu

Win.Popup – simple popup menu

To generate a simple right-mouse menu at the current mouse position:

Win.Popup 'One' 'Two' '' 'Lots'

Null entries make separators in the menu. This returns 0 if the user cancels, or the index of the menu item otherwise. You can grey out items, or check selected items by using the tilde and hash characters to begin the string:

Win.Popup 'One' '~Two' '#Three' '' 'Last'

Note that selecting ‘Last’ here will return 5 – the disabled and separator items are counted in the result. To use the radio button style (only one item may be selected for any menu group):

Win.Popup 'One' '' '∘This' 'That' '' 'Last'


CPro Turorial and Reference: Win.PopupTree – deep menu

Win.PopupTree – deep menu

This function builds a popup menu tree of any depth from an arbitrarily deep vector of text items:

      Win.PopupTree 'One' 'Two' ('Two-1' '#Two-2') '' 'Last'
2 2

It returns a vector of the indices of the selected menus and submenus, or 0 for <Cancel>

You can flag disabled, checked or radio-selected items as for Win.Popup.


CPro Turorial and Reference: Win.WhatsThis – "What's This" help

Win.WhatsThis – “What’s This” help

Dyalog currently support the ‘help’ event (400) on most objects, but there is no easy way of providing the help in the approved Windows style. This function can be set on the ‘Help’ event handler of any object, and passed a vector of text vectors to show as the help panel:

Help : ⍺ #.Win.WhatsThis 'Press to change date'

Note that the shadow effect is not quite perfect! Hopefully this function will be superseded by an appropriate internal call one day.


CPro Turorial and Reference: Win.Ync – Yes/No/Cancel dialogue

Win.Ync – Yes/No/Cancel dialogue

This is intended as the standard dialogue to be called when the application is closed. Normally you would put it on the ‘CL’ (Close request) event on the main form and reject the event if the user hit <Cancel>.

rc←Win.Ync 'Save changes to data?'

rc will be a scalar 1 for ‘Yes’, 0 for ‘No’ or 2 for ‘Cancel’ here.


CPro Turorial and Reference: Progress Bar Namespace

Progress Bar Namespace

The Progress Bar namespace is a small set of stand-alone utilities to create, update and check an ‘in your face’ progress box which you should use when you have a very long-running process. Typically it might look like:

The problem here is that you cannot ‘dequeue’ the form, as you will thereby suspend your long-running process. Instead you repeatedly check the state of the cancel button and abort the process if it has been pressed since you last checked.

#.GuiPbar.Open'Preparing Sales Summary'
#.GuiPbar.Set 0 total

... where total is the number you will be counting up to. If you leave this out, the default is 100, and the progress bar will show progress as a percentage.

#.GuiPbar.Close

... will remove the progress bar. To update it you call GuiPbar.Set repeatedly with the new counter and total values.

To check if the user recently hit the Cancel button:

abort←GuiPbar.State

Setting the message format and button caption

The default format for the message text is “? of #’ where ? is used as a placeholder for the counter and # for the total. You could also have “Printing page ? of #’ or ‘Processing files, ~ remaining of #” to count down.

To set the message format, pass it as the second item of the argument to GuiPbar.Open. You can also set the caption on the ‘Cancel’ button by passing a third argument – note that you should not use the standard ‘hotkey’ technique here as it will not be effective. The user must press the button with the mouse here!

Progress box example

This is a typical example of a long-running callback which might be set as the ‘Select’ action on a button:

 PBarStart
⍝ Run our progress bar until they stop us
 #.GuiPbar.Open'Off we go' 'Printing page ? of #' 'Abort Print!'
 :While 1000>ct←ct+1
   #.GuiPbar.Set ct 1000
  ⍝ Check every 100 - ensure the memory effect works!
   :If 0=100|ct
     :If 1=#.GuiPbar.State
       #.GuiPbar.Close
       :Return
     :End
   :End
 :End

If you call this from a causeway form, it will automatically be made as a child of the top form in the DQ. To use it stand-alone, you should pass the name of a suitable parent form as the left argument.


Tutorial: Building an Application

This tutorial takes you through the whole cycle of building a realistic application. You should probably allow at least 2 days to work through it fully.

  • How to Design a ‘Main’ Application
  • Writing the Application Code
  • Adding Menus and Toolbars
  • Putting in ‘Proper’ Windows File Behaviour
  • Calling a Subsidiary Dialogue (Using a Grid)
  • Linking to a Help File
  • Running it for Real
  • Gaining Speed and Saving Disk Space
  • Running Causeway from QuadSE


CPro Turorial and Reference: How to Design a ‘Main’ Application

How to Design a ‘Main’ Application

This is the end-product of the first few sections of the tutorial. It is a small contact manager, with menu and toolbar, a list box of current contacts, and a pop-up incident log implemented as a Dyalog grid. It also has all the ‘correct’ Windows file-management behaviour and keeps a list of the recently used files. It will take 4–5 hours to work through these examples, but by the end of the process you will have learned most of what there is to know about Causeway!

As before, let’s start with some test data, but this time it is worth setting up a function to build it as we will need this soon enough to run from File, New on the main menu:

     ∇ NEWFILE
[1]   ⍝ Do what we need to clear data down
[2]    ∆names←,⊂'Noname'
[3]    ∆addrs←,⊂'House' 'Street' 'Town' 'PostCode'
[4]    ∆eyes←,1
[5]    ∆log←,⊂0 2⍴0 ''
[6]    ∆was←∆names ∆addrs ∆eyes ∆log
     ∇

This avoids the annoying empty case by setting up one row of dummy data to start with. It takes a snapshot of the data it made so that the application can prompt on exit if any data has changed.

Building the basic form definition is much as before, but there are one or two new tricks to look out for. The data for the Name field will now be indexed from the vector of names:

... where inx is set as the data of the list box to its left.

You can make inx a local variable on the form, and initialise it to 1 when the form is created. To localise it, simply add it to the locals list in the property watcher; and set it on creation in the event table for the main form (right mouse menu – Behaviour on the form itself):

There is one other entry in this grid which needs to be explained:

  • many Causeway classes have internal functions (what the C programmers call ‘methods’) which you can run using the #.CPro.Do utility. This takes the object name as left argument, and the function name (in quotes) and its arguments on the right. In this case you can use the shorthand ⍺ for the name – meaning ‘self’ – to run the SetIcon function with the name of the .ico file you want to use for the main form. This example also abbreviates #.CPro. to ∇ which has the advantage that if you ever relocate the CPro namespace your dialogue boxes will not need modification, as Causeway will always substitute this correctly.

For the moment, just localise inx by adding it to the ‘locals’ property of the form, and add the second line to your table to initialise it – we can sort out the icon later!


CPro Turorial and Reference: Adding Menus and Toolbars

Adding Menus and Toolbars

In Causeway, you define menus as simple text variables. This is partly to make them easy to edit, and also to allow the possibility of saving several alternative menus on file if you need to make your system language-independent. The basic format of a Causeway menu is:

[Root]
 &File>file
 &Help>help

[file]
 &New  : NEWFILE ⋄ ∆file←'(untitled)' ⋄ inx←1 : ∆file,inx
 &Save : SAVEFILE ∆file
 -------------
 E&xit:∇Post 'SC'
[help]
 &About:#.Win.Msg 'My Program' 'Keep off'

Each menu or submenu is entered in a section, with its name in [brackets] like this. Note that these names are case-sensitive! The menu items start with a caption, and are then followed either by a > symbol (which points to a sub-menu section) or a colon and the APL code to execute when the user selects this menu item. Optionally, you may add another colon and a list of names to holler (separated by commas as for the event table).

To try this out, make a vector of text (mm←'[Root]' '') and edit it to look like the example above.

Then call up your form and set the menu name as the Menu property on the main form. You might also like to set the Titlebar property to an expression such as:

∆file,' - Contacts'

... with a dependency on ∆file. Note that the form must update the titlebar when the filename changes – that is why you ‘hollered’ it in the menu-item action.

Now when you CPro.Call the form you will have a working menu, and you can check out File,New and File,Exit. This uses another of the Causeway utilities CPro.Post to send an event to another object – in this case it sends a ‘System Close’ to itself (as far as Causeway is concerned, a menu is just a property of the form, so this closes the form). We could equally well have chosen to:

CPro.Return 'All done'    ... or
⍺ CPro.Do 'Close'

... but note that this last example gives no possible opportunity for your application to intervene with an “Are you sure?” – it just closes.

Adding Hints and Shortcut Keys

If you start any standard Microsoft application, you will see that as you run the mouse down the menu you get an expanded description of the caption in the status bar at the foot of the form. It has also become the norm to allow Ctrl+N as a shortcut for File,New and Ctrl+S to serve as File,Save. To specify these in the menu definition requires a little overloading of the caption:

[file]
 &New=Ctrl+N;Clears a new contacts file: NEWFILE
 &Save=Ctrl+S;Saves your work to the current file: ...
... and so on

To set the shortcut key, use any combination of Alt+Shift+Ctrl+A – Z or the same combinations +F1 – F12, Home, End, PgUp, PgDn, Enter, Esc. Note that the longer text is a very good source of documentation for the maintenance programmer, as APL allows you to double-click anywhere in a text vector to edit the name at the cursor. Even if you don’t need these hints for the user, add them for yourself, or whoever comes after you, as executable documentation.

Here is the menu I made for the contacts application:

      ↑menu_main
[Root]
 &File>file
 &View>view
 &Help>help

[file]
 &New=Ctrl+N;Clear all data         : NEWFILE ⋄ ...
 &Open=Ctrl+O;Open an existing file : OPENFILE ...
 &Save=Ctrl+S;Save your work        : SAVEFILE ...
 Save&As;Save with a new name       : SAVEFILE ...
 -------------
 E&xit:∇Post 'SC'
[view]
 &Options:#.Win.Msg 'Preferences'
[help]
 &About:#.Win.Msg 'My Program' 'Keep off'

Just as with dialogue boxes, it is a good idea to invent a convention for menu names and stay with it. I normally use menu.xx as the menu that associates with dbx.xx, but you might want to keep all your menus and dialogues together in the same namespace.

Including the Same Options on a Toolbar

In Causeway, you treat toolbars just like any other kind of form – you can even run them stand-alone to test out the actions. You then make them as part of the Create action on the main form and they duly attach themselves to the appropriate edge of their parent. Long thin toolbars stretch themselves out along the top edge and tall ones snap to the left edge.

For a horizontal toolbar, the depth of the bar is set by the vertical dimension of the form – this is a change from Causeway ‘shareware’ when the designed shape of the toolbar was completely ignored. To get a toolbar nicely resized, use the Causeway utility #.Class.MakeBar, which checks the bounding box of the tools that you define and makes the tool bar deep enough to enclose all of them, leaving a symmetrical margin top and bottom (or side-to-side for a tall toolbar).

To design our new toolbar we specify a particular form class as the left argument to Dbx:

 'tb' Dbx 'dbx.tb'
 dbx.tb←#.Class.MakeBar dbx.tb   ⍝ Tidy up the form shape

... I have added a tool button and set its caption to the special value ‘*New’ which will invoke Dyalog’s built-in bitmap for this operation. The Designer does not show captions on tool buttons – instead you see the caption as a pop-up tip when the mouse is over the button.

Check out the Cue-card on the right-mouse menu for tool buttons to see what other built-in bitmaps are available, and note that you can set your own tips and bitmaps. For the moment, just add tool buttons to duplicate File,Open and File,Save, and possibly a Close button anchored right. The finished dialogue box could look a little like:

     Disp dbx.tb[;1 2 5]

┌──┬──────────┬──────────────────────────────────────────────────────┐

│TB│(untitled)│┌────┬────┐                                           │

│  │          ││    │    │                                           │

│  │          │└────┴────┘                                           │

├──┼──────────┼──────────────────────────────────────────────────────┤

│TL│*New      │┌─────────┬──────────────────────────────────────────┐│

│  │          ││Behaviour│┌──┬┬────────────────────────┬───────────┐││

│  │          ││         ││SL││NEWFILE ⋄ ∆file←’(un... │{∆file│inx}│││

│  │          ││         │└──┴┴────────────────────────┴───────────┘││

│  │          │└─────────┴──────────────────────────────────────────┘│

├──┼──────────┼──────────────────────────────────────────────────────┤

│TL│*Open     │┌─────────┬──────────────────────────────────────────┐│

│  │          ││Behaviour│┌──┬┬────────────────────────┬───────────┐││

│  │          ││         ││SL││OPENFILE ∆file←#.Win... │{∆file│inx}│││

│  │          ││         │└──┴┴────────────────────────┴───────────┘││

│  │          │└─────────┴──────────────────────────────────────────┘│

├──┼──────────┼──────────────────────────────────────────────────────┤

│TL│*Save     │┌─────────┬───────────────────────┐                   │

│  │          ││Behaviour│┌──┬┬──────────────┬──┐│                   │

│  │          ││         ││SL││SAVEFILE ∆file│{}││                   │

│  │          ││         │└──┴┴──────────────┴──┘│                   │

│  │          │└─────────┴───────────────────────┘                   │

└──┴──────────┴──────────────────────────────────────────────────────┘

Now all we need to do is to add it to the event-action table of the main form, and the application begins to look quite professional!

            Disp ((⊂1 5),(⊂1 2))⊃dbx.mf

┌──┬┬────────────────────────┬──┐

│CR││⍺ ∇Do ‘SetIcon’ ‘cau... │{}│

├──┼┼────────────────────────┼──┤

│CR││inx←1                   │{}│

├──┼┼────────────────────────┼──┤

│PC││∇Make dbx.tb            │{}│

└──┴┴────────────────────────┴──┘

Kludge Alert! This example drew the toolbar correctly, because it was made on a Post-Create (PC) event, rather than on Create! Post-Create is a kludge – it runs after the first refresh of the object, so in this case it occurs after the menu has been added to the form. If you put the CPro.Make dbx.tb on the Create, the top line of the toolbar is not drawn properly, as Dyalog adds the menu over the top (by about 1 pixel) of the toolbar.


CPro Turorial and Reference: Putting in ‘Proper’ Windows File Behaviour

Putting in ‘Proper’ Windows File Behaviour

Virtually all Windows applications now protect their users against accidental replacement of existing data with a new file. Naturally, they also warn users against exiting with unsaved data. When you start to work through the logic needed to implement this in your APL system it all gets surprisingly complicated – for example if you try to clear from an (untitled) file the application must check if you changed anything, prompt for a file name, check that the name you supply does not already exist, and only then write to disk! Here is part of the decision tree:

No -- Clear

/

New -- Dirty?              No -- Clear

\             /

Yes -- Wanted?             Yes -- Save & Clear

\            /

Yes -- Named?                        No -- see above

\                       /

No -- Get name -- Exists?                Yes

^             \               /

|             Yes -- Overwrite?

|                             \

+---------<--------<--------<-No

... and of course there is the option to Cancel at any stage!

This is obviously one of those problems you want to solve once, and never have to think about again! One implementation of the solution is encapsulated in the Causeway NOSE (New-Open-Save-Exit) class – if you want to follow through the logic have a look at the FilePath function with )ed #.Class.NOSE.FilePath. The changes needed in the application code are (fortunately) nil, as we wrote it with Gui-independence in mind. All we need to do is to add a NOSE (under the Special submenu) to the main dialogue box and make some minor changes to the menu calls and tool button actions:

Here is the property browser for the nose – it will update the file name for us (∆file is set as its File property), but it needs to know how to prompt for it in the Windows filebox. This is why you should fill in something like:

'*.con' 'Contacts file'

... in the Specification property. It appears in the form (in the designer only) as a small square which is conventionally stuck in the top left corner, but of course you can put it wherever you like. Naturally, it has no visible caption, so it uses the caption you give it as a hint!

Now to change the main menu, but first a useful trick that you will come across frequently when building complex forms with interacting objects. We are going to want to run several built-in functions (methods) on the nose, and to do this we need its true (Dyalog) name as the left argument for CPro.Do. The easy way is to catch this name on creation, and set it as a local variable on the main form.

Here you can see that I have done the same trick for the status bar, which we will need shortly.

Now set up the event table for the nose itself to look like this:

  • Line-1 records its name (e.g. #.CPro.Root.FM12.NOSE23) as local var. nose.
  • Line-2 is run by nose whenever it needs to check if the user has changed some data. There are three possible strategies here:
    1. Always return 1. The user always gets prompted – safe but simple, and only mildly annoying.
    2. Snap the data whenever you pass a known checkpoint (after New, Save, Open) and compare the snap with the current state of the workspace. That is what I do here. Safe, but workspace-intensive for a large database.
    3. Set a global such as ∆∆SAVE to zero at the above checkpoints, and set it to one whenever you touch some data. Dangerous, in that you need to remember all the places where the user can touch something. Just set the action to ⍵←∆∆SAVE.
  • Line-3 is run (after all the required checks) when the nose has convinced itself that it is safe to do so. Note that the nose will set the file name to (untitled) by default, but you can over-ride this to set your own sequence of new names (Documentn or Sheetn). It is best to reset the list-box index here as there will only be a single entry in the new data set.
  • Line-4 runs your function to get the data, passing the file name it has been given by Windows in the standard file-box dialogue. I often forget the leading disclose – watch out!
  • Lines 5 and 6 run your save function and set the hint field in the status bar to a suitable short message. Note that this will vanish as soon as the user moves the mouse.

Now all we need to do is to set the actions on the menu to call the nose rather than running the file functions directly:

[file]
 &New=Ctrl+N;Clear all data : nose ∇Do 'New'
 &Open=Ctrl+O;Open an existing file : nose ∇Do 'Open'
 &Save=Ctrl+S;Save your work : nose ∇Do 'Save'
 Save&As;Save with a new name : nose ∇Do 'SaveAs'
 -------------
 E&xit:∇Post 'SC'

... and the same for the action table on the toolbar:

     Disp dbx.tbar[2 3 4;1 2 5]

┌──┬─────┬────────────────────────────────────┐

│TL│*New │┌─────────┬───────────────────────┐ │

│  │     ││Behaviour│┌──┬┬──────────────┬──┐│ │

│  │     ││         ││SL││nose ∇Do ‘New’│{}││ │

│  │     ││         │└──┴┴──────────────┴──┘│ │

│  │     │└─────────┴───────────────────────┘ │

├──┼─────┼────────────────────────────────────┤

│TL│*Open│┌─────────┬────────────────────────┐│

│  │     ││Behaviour│┌──┬┬───────────────┬──┐││

│  │     ││         ││SL││nose ∇Do ‘Open’│{}│││

│  │     ││         │└──┴┴───────────────┴──┘││

│  │     │└─────────┴────────────────────────┘│

├──┼─────┼────────────────────────────────────┤

│TL│*Save│┌─────────┬────────────────────────┐│

│  │     ││Behaviour│┌──┬┬───────────────┬──┐││

│  │     ││         ││SL││nose ∇Do ‘Save’│{}│││

│  │     ││         │└──┴┴───────────────┴──┘││

│  │     │└─────────┴────────────────────────┘│

└──┴─────┴────────────────────────────────────┘

Finally, we must allow the nose to intervene when the user hits File,Exit, or (in Windows 95) accidentally catches the X button at the top right of the form. Causeway always signals a Close Request (CL) event just before the main form exits – if you run an action which rejects this event, then the form will not be closed.

This is the first time you have seen the Condition column used in the event-action table. The nose will check if it is safe to exit, and return 1 if all the conditions are met (nothing to save, or the user hit No).

This leads to the rather odd double negative – if the condition is not true we must reject the event, so preventing the form from closing.

To explain the condition/action columns more formally:

  • For any event, Causeway takes the corresponding rows of the table and runs them in order. For each row, it executes the condition – if this evaluates to anything except 0 it runs the matching action.

    ... In this example, the condition runs the Exit function from the nose object, if this returns 1 it is safe for the user to leave – there is no unsaved data or he/she declined to save it. If it returns 0, the condition column is TRUE, so Causeway executes the action CPro.Reject. This stops any further processing of the table, and causes Dyalog to reject the event – so the form will not be closed.

That completes the introduction to the Causeway nose class. It is not simple, and you might well come back to these notes several times in the future – I often find myself checking existing applications as a reminder of how I coded it. Probably what you should now do is to spend some time testing your main dialogue, and exploring all possible branches of the decision-tree to prove that it really is impossible for your users to (accidentally) destroy their data.


CPro Turorial and Reference: Adding a ‘Most Recently Used’ List

Adding a ‘Most Recently Used’ List

A final touch to make your file system really user-friendly is to include an MRU list on the file menu. The idea is that whenever the user opens a file, or saves an existing file with a new name, the file is added to the list at the bottom of the file menu, or rippled to the top if it is already there. To add an MRU, select it from the Special submenu in the designer – it will appear as another small square which I have placed under the existing NOSE. Set up its data as:

Filename: ∆file

Specification: 'file' 'tutor' 6

As with the NOSE, it has the file name as the main data expression, so it will update this variable automatically for you..

The Specification is to tell it which menu to hang on, which .INI file to store the list in, and how many entries to save. Typically you would attach it directly to the ‘file’ menu (so that the recent files came below File,Exit on the menu) but another option is to make a completely empty menu as a child of the file menu and hang it from here:

[file]
 &Open .... etc
 &Recent files>recent
[recent]

.... and so on. This way you can have a much longer list (say 20 files) without overloading an already large menu.

It will make a new .INI file section the first time you use it (the .INI file will be created in the Windows directory if it does not already exist), with entries like:

[Recent File List]
File1=C:\DATA\DWS\Joe.con
File2=C:\DATA\DWS\Test.con

... and these will automatically appear at the bottom of the menu you specified (the ‘file’ menu in the example).

The action table must (of course) ask the nose to open the selected file, but this time it passes in the name and so bypasses the file dialogue:

      Disp (dbx.main[;1]⍳⊂’MRU’)⊃dbx.main[;5]

┌─────────────┬────────────────────────────────┐

│File name    │┌──────────┬───────┐            │

│             ││Expression│∆file  │            │

│             │├──────────┼───────┤            │

│             ││Dependence│{∆file}│            │

│             │└──────────┴───────┘            │

├─────────────┼────────────────────────────────┤

│Specification│┌──────────┬────────────────┐   │

│             ││Expression│’file’ ‘tutor’ 6│   │

│             │└──────────┴────────────────┘   │

├─────────────┼────────────────────────────────┤

│Behaviour    │┌──┬┬────────────────────┬─────┐│

│             ││FO││nose ∇Do ‘Open’ (⊃⍵)│{}   ││

│             │├──┼┼────────────────────┼─────┤│

│             ││FO││inx←1               │{inx}││

│             │└──┴┴────────────────────┴─────┘│

└─────────────┴────────────────────────────────┘


CPro Turorial and Reference: Linking to a Help File

Linking to a Help File

This is quite simple to do, once you have made the help file in the first place! You can go in at the top level (the main contents page) with a simple utility such as #.Win.Help (in the Causeway workspace):

Win.Help '\apl\causeway\causeway.hlp'
6130000 Win.Help '\apl\causeway\Causeway'
'Geometry' Win.Help '\apl\causeway\Causeway'

... the second example goes in using a ‘context number’ to the help page for the Causeway FM class – I happen to know that the help numbers are computed from their class mnemonic in this way! Finally, you can use a keyword to get to a list of all the topics where the keyword occurs; this will go straight to the topic if the keyword has only one hit in the file.

Typically you would add a <Help> button to your dialogue definition, and use a call to Win.Help passing a context number on the left to go directly to the correct topic. You will also find that many text-editing classes offer a ‘Help Request’ event which is triggered for the field when the user presses <F1> in the field. This allows you to give field-level help if you really need this level of detail – in practice it may be better to use the field ‘Hint’ and ‘Tip’ properties here.

To add <F1> help to a form without cluttering it with an extra <Help> button, you could add a ‘Hidden’ control, set its Accelerator property to F1 and simply call Win.Help from its normal Select event with the appropriate number.

N.B. (Windows 95 users only) – if the help file has been compiled with the new ‘tree of books’ style of interface you should call #.Win.Help with ¯1 on the left to access the contents page.


CPro Turorial and Reference: Running it for Real

Running it for Real

The final stage in preparing an application for distribution is to set it to run automatically, start the main form, and sign out when the form closes. In Dyalog APL this is particularly easy, as you can find out whether you are in a runtime system with a simple query on root:

      '.' ⎕WG 'APLVersion'
 Windows 95/Windows NT  8.1.3  W  Development

This means that you only need to maintain one copy of the workspace – it can simply switch to runtime behaviour in a runtime interpreter. Here is the utility I conventionally set as my ⎕LX:

             ∇ __msg←{__msg}Run __lx
[1]   ⍝ Check if we are in runtime mode, and run ⎕lx
        under full trapping if so
[2]   ⍝ If in a devt system - just report it.
[3]   ⍝ Note that ∆lx should end with ⎕OFF
[4]   ⍝ For example   ∆lx←'Go ⋄ ⎕OFF'
[5]   ⍝               ⎕LX←'''Go ⍝ to test'' Run ∆lx'
[6]
[7]    →('Development'≡⊃⌽'.'⎕WG'APLVersion')↑__Skip
[8]    __msg←'The End' ⋄ #.CPro.⍙debug←¯1 ⋄ –__lx ⋄ →0
[9]
[10]  __Skip:→(2=⎕NC'__msg')↑0
[11]
[12]   __msg←'⎕LX is: ',__lx
     ∇

... and all you need for Go is a single line to CPro.Call dbx.main.

Error Trapping

When you are developing with Causeway, it is convenient to have some basic error trapping set on the refresh expressions for the various controls, and also on the actions run from events. The default situation is CPro.⍙debug←0 which simply reports all errors to the session. If you set ∆partial∇ debugging with CPro.⍙debug←1 this turns off the error traps and you get suspended at the point of error as normal.

For runtime use, you can set CPro.⍙debug←¯1 which routes all errors in dialogue-box expressions through #.CPro.ShowError, which provides a simple default handler. You can modify the error text, or simply run with debugging off and set your own (outer) trap in the ⎕LX. It is good practice to run with an outer trap anyway, as internal errors in Causeway class code are not caught by the above trap.

An easy and effective strategy is to ⎕SAVE the workspace with an easy-to-recognise name which will allow a reload at the point of the error with all Gui objects intact.

See also ...

Customising the Error Text


CPro Turorial and Reference: Gaining Speed and Saving Disk Space

Gaining Speed and Saving Disk Space

When preparing an application for shipping, there are three things you might consider doing to get it ‘out of the blocks’ a little faster, and to economise on disk space for your installation set.

Setting a Startup Banner

This is a new (until recently undocumented) trick which came in with Dyalog 7.2 and 8. It allows you to get a startup banner running almost instantly, which you can kill when the main application has loaded.

First, use Causeway as normal to make a pretty startup screen (set the form style to ‘Banner’) such as:

Snap it to the clipboard as a bitmap (click on it, then press Alt+PrintScrn) and save it as a bitmap file with Paintbrush. To save a little space, use a package such as Paintshop Pro to save it as a Windows RLE file (in 16 colours). Then add a new string value greet_bitmap to the Dyalog-8 section in the Registry (look down the trail HKEY_CURRENT_USER, Software, Dyadic, Dyalog APL/W 8) with the value “.\banner.rle”. When you start your application proper, the Go function will need to kill off the banner with:

2 ⎕NQ'.' 'GreetBitmap' 0

You can do this as the first thing in the ⎕LX, or leave it as a Post-Create action on the main form. You might even want to set it as the action on a timer – on a very fast machine your users might not get time to admire the picture, or to read your copyright notice!

Sleeping Forms

If you have built any Causeway forms with more than 10 or so controls, you will have begun to notice the time taken between CPro.Call and the form becoming visible. On the main application dialogue this does not matter too much, but if you constantly call modal child forms you will need a way to get them on screen more quickly. The following technique can be used to build them once only, and from then on simply hide and show them (refreshed with the latest data) as required.

Two things to note here:

  • The Close Request is intercepted, and replaced by a call to #.CPro.Sleep. This has the effect of hiding the form and turning off all automatic refreshing of data. This is essential, as fields on the form might be watching local variables in a function no longer on the stack! The event must then be rejected to prevent the form from subsequently closing itself.
  • The form should be given a group id such as LOG. This should be unique, and easy for you to remember! I normally use upper-case for these, which makes them stand out a little.

You can do this for as many forms as you like, including the main application. In this case, you should make sure that you save the workspace with the form still in place, but asleep, i.e. do not run CPro.Clear before you save the final copy.

We must now add some logic to the calling function to make the form first time around, and then just recall it. Here is the code for Go and Log, suitably modified:

Go;fm
2 ⎕NQ'.' 'GreetBitmap' 0
:If 0=⍴fm←#.CPro.Id'MAIN'
  #.CPro.Call dbx_main  ⍝ 1st time in
 :Else
  #.CPro.Recall⊃fm
:End

Log inx;log;name;fm
⍝ Update incident log for this record
log←inx⊃∆log
⍝ Add a new entry for today
 log⍪⍨←(cal_ts 3↑⎕TS)''
 name←inx⊃∆names
⍝ Reuse sleeping form if available
 fm←#.CPro.Id'LOG'
 :If 0∊⍴fm
   res←#.CPro.Call dbx_log
  :Else
   res←#.CPro.Recall⊃fm
 :End
⍝ Update with new data unless <Cancel> was pressed
 :If res≠0
   (inx⊃∆log)←log
 :End

CPro.Id returns the true names of all extant objects with a given group id – in this there will be either none or exactly one. If the result was empty, we simply call the form as normal. If CPro.Id returned something, we recall the first item on the list. Naturally, both CPro.Call and CPro.Recall can take a left argument and return a result in exactly the same way.

If you want to make sure your form is really sleeping (and has not completely vanished from the system):

      #.CPro.Forms
'#.CPro.Class.Root.Control.FM44'  ⍝ (untitled)

This will list all current forms, including sleeping ones, commented with their titlebar and surrounded with quotes to make it easy for you to modify the line in the APL session and explore the raw Gui aspects of the form.

Clearing Unused Classes

Causeway is shipped with a full set of classes, some of which are quite complex and take a significant amount of workspace. Before you finally ship your application you can use dbx.enum to remove any classes which it does not require (this assumes that all variables in this namespace are dialogue boxes):

 r←enum;nl
⍝ List all classes used in all variables in this namespace
⍝ Assumes that everything it finds is a dialogue box!
 nl←↓⎕NL 2 ⋄ r←''
 :If 0<⍴nl
   r←∪(⊃⍪/⎕OR¨nl)[;⎕IO]
 :End
)cs #.Class
⎕EX ¨↓Classes~#.dbx.enum  ⍝ Remove unused classes
#.CPro.Build   ⍝ Regenerate Causeway's class list

You can easily add classes back in with Class.GetCls 'xx' but do remember to rerun #.CPro.Build after any such change to the current class list.


CPro Turorial and Reference: Running Causeway from QuadSE

Running Causeway from QuadSE

The various namespaces shipped with CausewayPro are designed to be easy to rename and relocate. You might like to move both the Designer and Picture Strip editor into your Dyalog session, to avoid saving these in every workspace you are in the process of building. To do this, simply relocate the namespaces ...

)cs ⎕SE
'' ⎕NS '#.Designer' '#.Strip'
)cs
)erase Designer Strip

and edit Dbx to refer to ⎕SE.Designer as appropriate. If you want to run DbxLoc from the session, this is equally simple, and you might consider setting a function key to save some typing if you use it regularly.

Moving the CPro namespace

Again, you can relocate the namespace with no problems, however you must carry out two extra steps before you try to run it:

  1. Tell the Designer where to find Causeway
  2. Re-initialise Causeway

You will find a variable in the designer namespace called Designer.∆causeway – you must reset this to give the full path name to the new location of the CPro namespace:

⎕SE.Designer.∆causeway←'⎕SE.Causeway'

You must now run the Causeway Initialise function which will update the class libraries with the same information:

⎕SE.Causeway.Initialise ''

If you use the progress bar namespace, you should also reset ∆causeway here as for the Designer.

Moving the class library

You can run one or all of your class libraries from ⎕SE – a possible strategy would be to run the Causeway-supplied classes from here and your own from the saved workspace. If you want to move the class library Class to be ⎕SE.StdClass, you can use ⎕NS as normal, then you must tell Causeway where the class libraries are, for example:

⎕SE.Causeway.SetClassPath '⎕SE.StdClass' '#.UserClass'
⎕SE.Causeway.Build

At this point, you should be able to run the Designer as normal, design a simple form and run a test action on a button. Note that the CProQA workspace is shipped with an Init function which is used to reset everything just before a build is saved or shipped. This will need to be changed to take note of the new paths.

Application code

You should have no problems with actions in dialogue boxes if you stay with the recommended method of referring to all Causeway functions as {del}function-name. These are resolved at runtime and you need take no other action to have them point to the correct namespace.

You might like to cover any calls to #.CPro.Make, Call, Notify and so on with one-line functions – do NOT use assigned functions here as these can fail badly if their target namespace is moved or deleted.


Tutorials: Using the Complex Classes

This chapter covers some of the more complex Gui objects, such as tabbed subforms. You may want to base your code on the examples, all of which are in the Tutor namespace in CProQA.

SubForms
How to Make a Set of Tabbed Subforms
MDIFrame
How to Set up MDI Children
MDIns
Using Namespaces with MDI
RainForm
Adding a Simple Chart from RainPro
NewLeaf
Building a Print Preview for NewLeaf
NewClass
Adding a New Class


CPro Turorial and Reference: How to Make a Set of Tabbed Subforms

How to Make a Set of Tabbed Subforms

The final few sections of this tutorial cover some odds and ends which we did not need for our sample application. Tabbed dialogues are conventional for setting preferences, although when overdone in Word97 style they can be totally confusing – try to stay with a single row of tabs if at all possible! Here is the kind of layout that makes some sense:

There are a couple of tricks to look out for – the Close button must be placed in exactly the same spot on both subforms, so make the first and copy it to the second, as shown below.

      'tsf' Dbx 'dbx.pref1'
Dialog box dbx.pref1 updated
      dbx.pref2←dbx.pref1
      Dbx 'dbx.pref2'
Dialog box dbx.pref2 updated
      Dbx 'dbx.prefs'
Dialog box dbx.prefs updated
     CPro.Call dbx.prefs

By default, the last form opened gets its tab to the front. To give focus to the first one, set up the event-action table on the parent form like this:

     Disp dbx.prefs[;1 2 5]

┌──┬───────────┬─────────────────────────────────────────────┐

│FM│Preferences│┌─────────┬─────────────────────────────────┐│

│  │           ││Behaviour│┌──┬┬────────────────────────┬──┐││

│  │           ││         ││CR││sf←∇Make¨dbx.pref1 d... │{}│││

│  │           ││         │├──┼┼────────────────────────┼──┤││

│  │           ││         ││CR││(⊃sf) ∇Do ‘ToFront’     │{}│││

│  │           ││         │└──┴┴────────────────────────┴──┘││

│  │           │├─────────┼─────────────────────────────────┤│

│  │           ││Locals   │{sf}                             ││

│  │           │├─────────┼─────────────────────────────────┤│

│  │           ││Style    │{Dbx}                            ││

│  │           │└─────────┴─────────────────────────────────┘│

└──┴───────────┴─────────────────────────────────────────────┘

... obviously you could record the state the user left these in and re-open the dialogue at the correct tab.

Placing the Subforms in a Region

It is not essential to have the tabbed forms occupy the entire parent form, and you might want to make your dialogue look more like a standard Windows95 property box:

This example uses a ‘Containing region‘ on the main form, in addition to the obvious <OK> and <Cancel> buttons. The region has as one of its properties a list of dialogue-box definitions to be added as its children – these automatically occupy the entire available space, but are now constrained by the inner container rather than the entire form.

Here is the definition which produced the simple example shown above:

      Disp dbx.prefsub[;1 2 5]

┌───┬───────────┬─────────────────────────────────────────────┐

│FM │Preferences│┌┬┐                                          │

│   │           ││││                                          │

│   │           │└┴┘                                          │

├───┼───────────┼─────────────────────────────────────────────┤

│EN │OK         │┌┬┐                                          │

│   │           ││││                                          │

│   │           │└┴┘                                          │

├───┼───────────┼─────────────────────────────────────────────┤

│QT │Cancel     │┌┬┐                                          │

│   │           ││││                                          │

│   │           │└┴┘                                          │

├───┼───────────┼─────────────────────────────────────────────┤

│RGN│           │┌────────┬──────────────────────────────────┐│

│   │           ││Subforms│┌──────────┬─────────────────────┐││

│   │           ││        ││Expression│dbx.pref1a dbx.pref2a│││

│   │           ││        │└──────────┴─────────────────────┘││

│   │           │└────────┴──────────────────────────────────┘│

└───┴───────────┴─────────────────────────────────────────────┘

Clearly, this gives you much more flexibility in designing this kind of ‘notebook’ interface – you could even have several sets of related tabbed boxes in the same parent form, or a radio-button group on the left which determined the set of notebook pages shown in the container on the right. In general this will be less confusing to the user than multiple banks of tabs, and is very much better than offering a scrolling tab-bar.

There is an example dbx.prefsubs in the Tutor namespace which makes this type of compound selector:

You might like to experiment with this layout, for example by right-aligning the tabs on the subforms, to produce a setup dialogue which copes well with several sets of related options.


CPro Turorial and Reference: How to Set up MDI Children

How to Set up MDI Children

In Causeway, the MDI parent form is treated no differently from any other main form – the only thing to remember is that the child forms are made as a special ‘MDI child’ class. Typically you would localise all your working variables on the child form, and read them from file on its create event, probably passing the file name as an argument to #.CPro.Make. In this example I have a simple notepad field on each child, with the content set to the form’s Dyalog Gui-name on creation:

Here the main form makes the toolbar and creates two children:

      Disp dbx.mdip[1;1 2 5]

┌──┬──────────┬─────────────────────────────────────────────┐

│FM│Sample MDI│┌─────────┬─────────────────────────────────┐│

│  │          ││Behaviour│┌──┬┬────────────────────────┬──┐││

│  │          ││         ││CR││top←’’                  │{}│││

│  │          ││         │├──┼┼────────────────────────┼──┤││

│  │          ││         ││PC││∇Make #.Class.MakeBa... │{}│││

│  │          ││         │├──┼┼────────────────────────┼──┤││

│  │          ││         ││PC││∇Make¨2⍴⊂dbx.ch         │{}│││

│  │          ││         │└──┴┴────────────────────────┴──┘││

│  │          │├─────────┼─────────────────────────────────┤│

│  │          ││Locals   │{top}                            ││

│  │          │├─────────┼─────────────────────────────────┤│

│  │          ││Titlebar │┌──────────┬───────────────────┐ ││

│  │          ││         ││Expression│’Sample MDI – ‘,top│ ││

│  │          ││         │├──────────┼───────────────────┤ ││

│  │          ││         ││Dependence│{top}              │ ││

│  │          ││         │└──────────┴───────────────────┘ ││

│  │          │├─────────┼─────────────────────────────────┤│

│  │          ││Menu     │┌──────────┬────────┐            ││

│  │          ││         ││Expression│menu_mdi│            ││

│  │          ││         │└──────────┴────────┘            ││

│  │          │├─────────┼─────────────────────────────────┤│

│  │          ││Topform  │┌──────────┬─────┐               ││

│  │          ││         ││Expression│top  │               ││

│  │          ││         │├──────────┼─────┤               ││

│  │          ││         ││Dependence│{top}│               ││

│  │          ││         │└──────────┴─────┘               ││

│  │          │└─────────┴─────────────────────────────────┘│

└──┴──────────┴─────────────────────────────────────────────┘

... and the children set up their data:

      'mdi' Dbx 'dbx.ch1'

     Disp dbx.ch[;1 2 5]

┌───┬────────────┬─────────────────────────────────┐

│MDI│Child Window│┌─────────┬─────────────────────┐│

│   │            ││Behaviour│┌──┬┬───────┬──┐     ││

│   │            ││         ││CR││notes←⍺│{}│     ││

│   │            ││         │└──┴┴───────┴──┘     ││

│   │            │├─────────┼─────────────────────┤│

│   │            ││Locals   │{notes}              ││

│   │            │├─────────┼─────────────────────┤│

│   │            ││Menu     │┌──────────┬────────┐││

│   │            ││         ││Expression│’window’│││

│   │            ││         │└──────────┴────────┘││

│   │            │└─────────┴─────────────────────┘│

├───┼────────────┼─────────────────────────────────┤

│NP │            │┌────┬────────────────────┐      │

│   │            ││Text│┌──────────┬───────┐│      │

│   │            ││    ││Expression│notes  ││      │

│   │            ││    │├──────────┼───────┤│      │

│   │            ││    ││Dependence│{notes}││      │

│   │            ││    │└──────────┴───────┘│      │

│   │            │└────┴────────────────────┘      │

└───┴────────────┴─────────────────────────────────┘

The other two important things to set up are the window menu for the main form, and the corresponding Menu property for each child.

The main menu now looks like this ...

      ↑menu_mdi
[Root]
 &File>file
 &Window>window
 &Help>help

[file]
 &New=Ctrl+N;Adds a New child window: ∇Make dbx.ch
 &Open=Ctrl+O;Open an existing file : 'Open'
 &Save=Ctrl+S;Save your work : 'Save'
 Save&As;Save with a new name : 'SaveAs'
 -------------
 E&xit:∇Post 'SC'

[window]
 Tile &Horizontal: ⍺ ∇Do 'Htile'
 Tile &Vertical: ⍺ ∇Do 'Vtile'
 &Cascade: ⍺ ∇Do 'Cascade'

[help]
 &About:#.Win.Msg 'My Program' 'Keep off'

The setting of the Menu property of the MDI child to ‘window’ allows Causeway to make the connection between the children and the menu structure on the main form (called [window]), so that as we add more windows they are listed automatically at the end of the window menu and the user can switch between them even when they are maximised.

Starting with a Clear MDI Frame

Because Causeway only fills in the MDI backdrop when you make the first child, a small cheat is required if you want to start the application with no child windows open. Make a dummy MDI child form (just 'MDI' Dbx 'dbx.dummy' and save immediately) and set the post-create action on the parent to:

(∇Make dbx.dummy) ∇Do 'Close'

... which makes the child form (the parent is still hidden, so nothing shows on the screen) and immediately discards it.

Running Toolbar Actions on the MDI Children

A major complexity added by MDI is that toolbar and menu actions must act on the child form which is currently at the top of the heap. You may have noticed that the parent form localises a variable top and sets this as the data expression for the Topform property. This is also shown in the titlebar of the main form, so that we can see it change as the child forms are brought to the top of the stack. If you try running this example and switch between the child forms you will see how Causeway maintains this property for you.

A simple extension to the toolbar is to make the <Close> button close down the current child:

Select: top ∇Post 'SC'

The next stage is to add some controls to the toolbar which modify the local data on each child. Here is the toolbar with two extra buttons to clear the notes field and flip its contents around:

... and here are the ‘Select’ actions on the two new buttons:

top ∇Execute 'notes←⌽notes ⋄ ∇Notify ''notes'''
top ∇ExecuteNR 'Wipe'

... where the Wipe function just looks like:

      ∇Wipe[⎕]∇
[0]   Wipe
[1]  ⍝ Clear down the notes
[2]   notes←'Hi'
[3]   #.CPro.Notify'notes'

The new functions you need to know about are #.CPro.Execute and #.CPro.ExecuteNR, which take any simple character vector and run it as if it were an action on the object which you pass as the left argument. This means that the expression has full access to all the locals on that form, and it can notify changes which will only apply locally – it does not matter that there is another form out there with locals of the same name! Note that you should use the NR version if your function does not return a result.

It is probably tidier to make small subfunctions (like Wipe) for all these actions, as otherwise you rapidly get buried under strings of quotes. Also it is often very convenient to stop the code (for example on line-2 of Wipe) where you can inspect the variables, try out expressions, paste bits of code from the session into the definition, and so on.

As a final refinement, you might make the <Close>, <Wipe> and <Flip> buttons inactive unless there is at least one child form available. You could add an expression such as:

0<⍴top

as the ‘Active’ property of each of them (with a dependency of ‘top’, naturally), or you could put them all into a group and run 'BTNS' ∇Do 'Disable' or 'Enable' as appropriate from a Post-Update handler on the top variable. The former is easier to code, the latter may be faster if you have lots of buttons.


CPro Turorial and Reference: Setting Chart Options

Setting Chart Options

It would be nice to give the user some control over the look and feel of the chart, for example by setting the heading, or requesting markers rather than a filled line. Here is a slightly more refined version:

... where I have taken the actions out of the event table and returned the completed chart from a simple function:

     ∇r←MakeCht sz
[1]   ⍝ Set up chart to fit in given space
[2]    #.ch.New 0 0,⌽sz
[3]    #.ch.Set'noline,nomark,nofill'
[4]    #.ch.Set⊃,/chopt/'line,' 'mark,' 'fill'
[5]    #.ch.Set'head'chttl
[6]    #.ch.Plot+\?123⍴12
[7]    r←#.ch.Close
     ∇

Note that the window size is passed in as an argument – if I had included any Gui code within the function I would have made it impossible to test it from the session! I have left chopt and chttl as globals for the same reason; they are probably the kind of data you would save on an INI file anyway, so they would be local to your startup function or saved in a suitable namespace such as #.workvars.

There is one interesting new technique illustrated by the event tables on the first and last check boxes:

Lines: Validation: chopt[3]^←⍵

Filled: Validation: chopt[1]Ÿ←⍵

It makes no sense to have fill without lines, so when the user unchecks the Lines box the Fill box is also cleared and when Fill is checked, Lines is checked also! This is done on a Validate event which is run by Causeway between the object being examined and the data from it being put back into the target variable. The actual data is available as ⍵ in the event table; you can modify it in passing, reject the event (in which case the field is restored to its previous value) with CPro.Reject, or just set some other data to match.

In this case there was no need to holler chopt, because the change would be signalled automatically by Causeway as long as the validate was not rejected. If I had set a different variable, rather than just another element of the same variable, I would have needed to signal the change.


CPro Turorial and Reference: Building a Print Preview for NewLeaf

Building a Print Preview for NewLeaf

The job of building a simple Print Preview screen is very similar to displaying charts from Rain. However it also illustrates several other useful techniques, including the use of a progress bar which may be necessary if you are generating a very large report.

This shows a simple sales summary (randomly generated) which runs to a three-page listing. The user can use the VCR control to run through the report or call a secondary dialogue to print it. While the report was building the screen showed a progress bar such as:

This clicks over once per section – we do not know at this stage how many pages the report will run to!

The next few pages run through the code needed to set up and increment the progress bar and build the report with NewLeaf.

Please refer to the NewLeaf User’s Guide for a full explanation of the syntax used to construct the table.

The first requirement is to copy the leaf namespace (and the PostScrp viewer unless you already have it) and check that it works:

      )copy newleaf leaf PostScrp
.\NL78 saved Tue Aug 27 17:54:24 1996
      #.leaf.Use ''
      #.leaf.table.List 12 4⍴⍳123
      PG←#.leaf.Close
      #.leaf.NumPages PG    ⍝ How many pages?
1
      #.PostScrp.View PG    ⍝ Check it on screen
      )ed PG   ⍝ Check preview box in page definition
      .5×842 595   ⍝ Paper size in points
421 297.5

The page description of your sample report is held in a simple text variable PG, returned by #.leaf.Close. You can look at this with )ed to check the page size (in points), which gives you the proportions needed for a page-preview. In this case I used A4 portrait paper, so a good size for a monitor is 800 by 600 pixels. Now we can go ahead and design the dialogue box for a simple page preview:

      Dbx 'dbx.pv'
Dialog box dbx.pv updated

The new objects you need are the PostScript Viewer (from the Special menu) and the VCR buttons. You can also add a Close button, and I find that the viewer looks good with a frame – use the Frame button on the lower toolbar to add this. We can return to the Print button when the basic viewer is working nicely.

┌──┬┬─────────────────────────────┬───────┐

│CR││pn←np←0                      │{}     │

├──┼┼─────────────────────────────┼───────┤

│PC││⍺ ∇Do ‘Show’                 │{}     │

├──┼┼─────────────────────────────┼───────┤

│PC││spl←make_report 7            │{spl}  │

├──┼┼─────────────────────────────┼───────┤

│PC││np←#.leaf.NumPages spl ⋄ pn←1│{np│pn}│

└──┴┴─────────────────────────────┴───────┘

On creating the form I have initialised a couple of local variables to hold the current page number and the total number of pages The form is then made visible (just to give the user something to see) and the report is constructed. When it completes, it updates the name of the spool file (which is set as the PostScript property of the preview) and checks how many pages were generated.

The properties for the PostScript viewer are set up as:

      Disp ⊃dbx.pv[2;5]

┌──────────┬──────────────────────────┐

│Behaviour │┌──┬┬─────────────────┬──┐│

│          ││ZM││⍺ ∇Do ‘Rescale’ ⍵│{}││

│          │└──┴┴─────────────────┴──┘│

├──────────┼──────────────────────────┤

│Page No   │┌──────────┬────┐         │

│          ││Expression│pn  │         │

│          │├──────────┼────┤         │

│          ││Dependence│{pn}│         │

│          │└──────────┴────┘         │

├──────────┼──────────────────────────┤

│PostScript│┌──────────┬─────┐        │

│          ││Expression│spl  │        │

│          │├──────────┼─────┤        │

│          ││Dependence│{spl}│        │

│          │├──────────┼─────┤        │

│          ││Forced    │1    │        │

│          │└──────────┴─────┘        │

└──────────┴──────────────────────────┘

Note that again the refresh has been forced, this time because we are passing the name of the spool file, which may not change even though the content could be completely different.

Operating a Progress Bar

One of the namespaces you may have noticed in the Causeway workspace is #.GuiPbar. This contains the functions to set up a simple progress bar, update it as required and check for a cancel request from the user. To start a new progress bar, simply:

 #.GuiPbar.Open'Preparing Sales Summary'
 #.GuiPbar.Set 0 total

... where total is the number you will be counting up to. If you leave this out, the default is 100, and the progress bar will show progress as a percentage.

The effect is to make a form centred on the screen with the initial state:

To get rid of it (pressing the Cancel button has no effect):

#.GuiPbar.Close

... will remove the form. To update it (remember that it cannot be in a ⎕DQ as your application will wait for it and stop processing!) you call:

#.GuiPbar.Set 23

... and to check if the user hit the Cancel button:

cancel←#.GuiPbar.State

To see what it might look like in context, here is the complete function to build a big report, but allow the user to abandon processing mid-way:

PG←make_report n;m;sect;mat
⍝ Generate random report of n sections of up to m rows
 #.GuiPbar.Open'Preparing Sales Summary'
 #.GuiPbar.Set 1 n
 #.leaf.Use''
 'heading'#.leaf.Place'Sales Report for 1998'
⍝ Set up table properties
 #.leaf.table.Titles'Product' 'Description' 'Sales' 'Units' 'Value'
 #.leaf.table.TDepth 0 0 0 1 1
 #.leaf.table.Align'left' 'left' 'dec' 'dec2'
 #.leaf.table.TAlign'left' 'left' 'center' 'right' 'right'
 #.leaf.table.Qfmt'' '' 'I4' 'F7.2'
 #.leaf.table.Spacing 3 3
 #.leaf.table.Gridlines 1 0.4 0
 :For sect :In ⍳n
   m←?23
   :If #.GuiPbar.State ⋄ :Leave ⋄ :End
   #.GuiPbar.Set sect n
   'subhead'#.leaf.Place'Section ',⍕sect
   mat←m 2⍴'Widgets' 'High class widgets' 'Sprockets' 'Cheap bits'
   mat←mat,?m 2⍴123 2345
   #.leaf.table.List mat
   #.leaf.Group 2
:End
 #.GuiPbar.Close
 PG←#.leaf.Spool''

Printing the Previewed Page

NewLeaf supports several methods of printing (and clipboarding) the previewed page. The simple option is just to add an SL action to the Print button to call the standard Print function:

:SL: :#.PostScrp.Print spl::

This will print the entire document on the default printer with the orientation shown in the preview. Note that this may be different from the default printer setup. You can also choose the page numbers to be printed (call a suitable dialogue box to ask the user) and pass a vector of page numbers as the left argument of PostScrp.RunOff, which will otherwise print the entire spool file:

:SL: :req PostScrp.RunOff PG::

Some other possibilities which you might consider offering the user are:

  • saving the current page as an Encapsulated PostScript file for inclusion in DTP tools such as PageMaker. This requires a call to PostScrp.WriteEPS, passing the file name on the left and PG on the right. To read the current page back from a spool file you will need to use leaf.Fetch pn, where pn is the page number.
  • writing the report direct to a PostScript printer, or saving it in the Adobe Acrobat inbound directory for conversion to a .PDF file for Web publishing. You should call PostScrp.Write, again with the file name on the left. If you omit the file, prn is assumed. Note that this is much faster than using the normal Windows PostScript driver, and may under certain circumstances avoid rendering problems due to errors in many PostScript drivers.
  • save the page to the Windows clipboard (in placeable metafile format) for pasting into most Windows applications. Call PostScrp.Clip PG (or use leaf.Fetch to read the current page from the spool file) to clipboard the page. Note that this may take some time for a complex page and you should probably put up a ∆wait∇ cursor with '.' CPro.Do 'Wait' while it runs. Restore the normal cursor with '.' CPro.Do 'Ready'.

All the printing commands assume you have a black and white printer, and will map coloured text to solid black. If you want coloured output, set the global flag PostScrp.∆rgb to 1; you might also like to adjust the RGB mappings which you will find in PostScrp.∆chrgb. If you change either of these, make sure to take a copy so that you can re-apply your changes having upgraded the PostScrp namespace.


CPro Turorial and Reference: Adding a New Class

Adding a New Class

Although Causeway is supplied with over 60 Gui components, you will soon find that there is something you need that does not quite match the classes in the library. Don’t panic! CausewayPro has been designed to make it very easy to make minor modifications to existing classes, and comes with a template class library ready for you to start work on your own classes.

This example takes a simple requirement – to make a currency-based numeric edit field – and works through the process of building this as a new class and incorporating it into a test dialogue. For a full technical discussion of the class specification, please refer to the CausewayPro Reference Manual.

Making a New Class from the Template

The first stage is to clone the template class library. This keeps your classes separate from Causeway’s, and leaves you in no danger of losing your work next time you take an upgrade.

      'MyClasses' ⎕NS ⎕OR 'UserTemplate'
      )cs MyClasses
#.MyClasses

Now you are ready to make your new class from the supplied template ...

      )obs
Template
      'CCY' ⎕NS ⎕OR 'Template'
      ParseSpec 'CCY'
      Classes
 CCY

This library can be added to the list which CPro and the Designer know about ...

      #.CPro.SetClassPath '#.MyClasses' '#.Class'

... and you are ready to start creating the APL code needed to drive it.

      )cs #.MyClasses.CCY
#.MyClasses.CCY
      )fns
onKeyPress      Caption Create  Destroy Fns     Read    Refresh
      )vars
design  events  isParent        properties      readevents      specification

The place to begin is the specification – I suggest editing it to make something like this:

[Design]
Name=Currency Field
Type=Text
Size=24 ⍬   ⍝ Drag to width

[Read Events]
Value=36

[Properties]
Hint      : String
Labelled  : OneOf 'default' 'Left' 'Top' 'Bottom' 'Right'
Value     : User      ⍝ Numeric singleton ...

[Cue Card]
Shows a number in the current Windows currency format.

[Release Notes]
Based on text edit class.

Most of the sections should be self-evident – you can experiment later to see the effect of various changes on the way the class behaves in the Designer. The only crucial connection which must be made is between the ‘Value’ property and the [Read Events] section. Here you will see the line ‘Value=36’ which means that whenever the Dyalog event #36 occurs on the object (this is the ‘Changed’ event which is triggered on a text field when you leave it, having modified the data) Causeway should run the Read function to take the value from the field and assign it back to the APL expression associated with the ‘Value’ property.

Implementing the New Class

Now you can fix up the functions which will implement it – we need Create (to make it), Refresh (to take the value and update the field), Read (to get the data from the field) and Destroy (to clean up after it):

 this←Create defn;parent;ctl;cap;attach;posn;size;props;nl
⍝ Currency Edit class CCY
 (parent ctl cap attach posn size props)←defn
⍝ Note that caption must be created first
 this←parent,'.CCY',⍕ctl
⍝ Use supplied utility to label it, and record the name
 nl←this ##.Label defn
 this ⎕WC'Edit' ''posn size('Attach'attach)('Fieldtype' 'Currency')
⍝ Set up instance variables and correct ⎕IO etc
 ⎕CS this ⋄ ⎕IO←1 ⋄ ⎕ML←1 ⋄ names←nl
 vals Refresh this;props;value
⍝ Refresh function for CCY class
⍝ Allows for several properties (future proofed!)
 :For props :In ↓vals
   :Select ⊃props
    :Case 'Value'      ⍝ New value data
     value←⊃⌽props
     this ⎕WS'Value'value
   :EndSelect
 :EndFor

 val←prop Read msg
⍝ Read function for CCY (one property only)
 val←(⊃msg)⎕WG'Value'
 Destroy this
⍝ Remove caption when object is destroyed
 :If 9=⎕NC this
   ⎕EX⊃this⍎'names'
 :EndIf

This should now work, but first we must register it with Causeway. This is the stage I usually forget – if you start the designer and see no sign of your new class, then you need to:

      )cs #
#
      CPro.Build

Testing and Refining the Class

Now it is OK to set up some test data and design a small test form:

      nn←12.3
      Dbx 'qw'

Run it, check that the value appears correctly, and also check that when you click back to the session that the value of nn has been updated correctly. Here is how it might look:

One small refinement would be to set it to select all the text when it gets focus (and deselect it on a matching lostfocus). This simply involves adding a couple of standard event handlers to the existing Create function:

 events←⊂'Event'(40 'onGotFocus')(41 'onLostFocus')
 this ⎕WC'Edit' ''posn size('Attach'attach)('Fieldtype' 'Currency'),events

... which could look rather like:

 msg←onGotFocus msg
 ⍝ Select entire text
  (⊃msg)⎕WS'seltext'(0 255)
 msg←onLostFocus msg
⍝ Deselect on leaving
 (⊃msg)⎕WS'seltext'(0 0)

That really is all there is to it. You might like to run SaveCls 'CCY' to make a backup copy on disk, and possibly set up a more thorough QA test to ensure all the properties work as anticipated.


Reference Section

This section of the guide covers the CPro functions and class library.

Reference
Introduction to Reference Manual
Installation
Installing and Checking CausewayPro
Commands
Functions Common to All Classes
TechInfo
Other Technical Information

The help on the class library is available directly from the designer with F1.


CPro Turorial and Reference: Introduction to Reference Manual

Introduction to Reference Manual

This manual is intended primarily as a comprehensive technical reference to the CausewayPro software development environment. It does not attempt to cover concepts or provide worked examples – if you are learning the software, you may find it helpful to browse the class library section but you should also work through the tutorial examples in the companion Getting Started with Causeway booklet.

The sections cover installation and checking of the shipped software, the functions which you may call in the Causeway namespace, the supplied Gui objects which you use to build an application, and the generic function calls which you may use with any of those objects.

When you are comfortable with the basic approach of the Causeway environment, you will want to modify the supplied classes and design and implement new classes of object entirely. The section on Class Building shows you how to make new Gui object types which will integrate fully into the Causeway designer.

Finally you will find a short description of the standard events which most Gui objects support (many of these are supported directly by the interpreter, but Causeway adds some extra ones such as ‘Validation’ and ‘Post-Update’) and a detailed description of the dialogue-box format which CausewayPro now uses.


CPro Turorial and Reference: Installing and Checking CausewayPro

Installing and Checking CausewayPro

What you Get

CausewayPro is shipped as a Dyalog workspace, and this help file. You can simply copy the CPro workspace to your normal development directory or leave it as installed by Dyalog. The help file is expected to be within the \help subfolder in the Dyalog 12 installation.

Checking it out

To ensure your workspaces are correctly installed, load CPro and try designing a simple dialogue box:

      )load cpro
.\cpro saved Sun Jan 20 12:00:04 2008
.... CausewayPro 1.5 for Dyalog APL 12.0
      Dbx 'qw'
Designing qw

This should allow you to add some new objects to the form (use the right-mouse menu) – press F1 to get help on the current object and press F5 to run the form. Ctrl+Q will exit without saving any changes.

You might also like to check out the full set of example dialogue boxes designed to test the capabilities of every CPro class. You can run through the entire set with ...

#.QA.Seatrial ''

... just hit Ctrl+Break and type #.CPro.Reset if you get bored. Also you will find a small sample application (the one which is built up by the tutorial) which you can run with #.Tutor.Go.

What you need in your Application

The namespaces provided in CPro cover all you will need to build an run an application. They are:

dbx | a suggested repository for your dialogue boxes
Class | the ‘core’ class set (contains 42 class sub-namespaces)
CPro | the Causeway ‘engine’
Designer | the CPro form designer
Win | a selection of stand-alone windows utilities

The bare minimum for a working application is CPro and Class (with the classes used by that application only). You might like to keep the designer in ⎕SE.Designer to save on the disk space used by saved workspaces. For more information on alternative setups, see the section “Running Causeway from QuadSE” in the Getting Started section.

The code is commented, and all classes include a specification variable which is a handy reference point for the purpose and history of the class code.

      )ed #.Class.TX.specification

To see a typical example. You can erase any classes which you don’t need in your application, but be sure to run

#.CPro.Build

whenever you change the contents of the class library. This tells the Designer what is available, and it will adjust the list of classes on the right-mouse menu accordingly. A good idea would be to copy and modify the Init function from CProQA:

     Init
Rebuilding class documentation ...
Class specifications parsed ...
Causeway cleared & reset
Debug set to stop on error (1)
Picture-strip editor initialised
Initialised!

This runs all the initialisers and sets the crash behaviour and feedback message.


CPro Turorial and Reference: Functions Common to All Classes

Functions Common to All Classes

Standard methods (functions) which may be run from all CPro objects are:

  • Fns – lists any public functions in the class
  • Disable – inactivates the object (see note on Form)
  • Enable – reverses Disable (see note on Form)
  • Hide – hides the object
  • Show – makes the object visible again
  • Set – interpreter-specific commands
  • Caption – changes the object caption
  • Close – closes the object (removes it from the form, or closes it if it is a form)

Commands are run with:

 objname #.CPro.Do 'Command'

Commands which are specific to other objects are:

Root

  • Wait – to show a ‘wait’ cursor on the application
  • Ready – to restore normal cursor

Progress Bar

  • Set – sets the current % complete

Main Form

  • Check – to check a menu item
  • Uncheck – to remove a check mark
  • Wait – to show a ‘wait’ cursor on the application
  • Ready – to restore normal cursor


CPro Turorial and Reference: Other Technical Information

Other Technical Information

Causeway-generated dialogue boxes are saved in the workspace as standard APL matrices, so you can easily modify them under program control. Similarly the global class tables Class.∆styletab and Class.∆domain are intended for modification by the application developer.

Some of the objects and behaviours you might require more information about are:

The dialogue-box format

The global style table

The domains table for the grid classes The domains table for the grid classes

You might also like to see more about ...

The effective use of the style table

How Causeway manages the ‘Attach’ property How Causeway manages the ‘Attach’ property

Local variables on forms Local variables on forms

Defining menus with hot keys etc Defining menus with hot keys etc

The grid specification (for the TM and MA classes) The grid specification (for the TM and MA classes)

Designating hot-keys for any object Designating hot-keys for any object

Customising the default error-handler Customising the default error-handler

Please take care to preserve copies of modified tables as they are shipped with Causeway and there is obviously a danger that your changes will be lost when you install a new version.


Reference: CPro Function Reference

This section lists all the public functions in the CPro namespace. Only 5 or 6 of these are required in the majority of typical applications.

  • #.CPro.Accel
  • #.CPro.Append
  • #.CPro.Args
  • #.CPro.Build
  • #.CPro.Call
  • #.CPro.Clear
  • #.CPro.Do
  • #.CPro.Execute
  • #.CPro.Form
  • #.CPro.Forms
  • #.CPro.GetContext
  • #.CPro.Id
  • #.CPro.Init
  • #.CPro.It
  • #.CPro.IsAccelFree
  • #.CPro.ListAccelerators fm
  • #.CPro.Make
  • #.CPro.MakeAsleep
  • #.CPro.Menu
  • #.CPro.Notify
  • #.CPro.Parent
  • #.CPro.Parse
  • #.CPro.Post
  • #.CPro.Qna
  • #.CPro.ReadNow
  • #.CPro.Recall
  • #.CPro.Reject
  • #.CPro.Reset
  • #.CPro.Return
  • #.CPro.SetClassPath
  • #.CPro.SetFocusTo
  • #.CPro.Sleep
  • #.CPro.UpdateAllChildren
  • #.CPro.Wait
  • #.CPro.Wake
  • #.CPro.Zap


CPro Turorial and Reference: #.CPro.Accel

#.CPro.Accel

Setting Hot-keys on any Object

Adds hot-key support to any object.

Syntax:

obj #.CPro.Accel string

Causeway supports accelerators automatically on Menu Items, and several other classes (such as tool buttons and action buttons) have an ‘Accelerator’ property. If you need to set up a hot-key on any other object, simply add an action on ‘CR’ such as

⍺ ∇Accel 'Ctrl+A'

The object will then run its ‘Select’ action whenever Ctrl+A is pressed by the user. Note that this works for all objects, not only those which have a ‘Select’ event as standard.

See Accelerators for more information.


CPro Turorial and Reference: #.CPro.Append

#.CPro.Append

Add Extra Controls to an Existing Dialogue

You may occasionally need to add further controls to an existing dialogue.

Syntax:

obj #.CPro.Append dbx_defn

Call #.CPro.Append, passing the name of the form on the left, and a matrix (or vector if you only want one new control) giving the appropriate rows from a standard dialogue box definition on the right:

gui←#.CPro.Make dbx.one
gui #.CPro.Append dbx.two[2 4 12;]

Note that you should not pass the first row of a normal dialogue box here, as this will make a child form in the usual way!


CPro Turorial and Reference: #.CPro.Args

#.CPro.Args

Capturing Form Arguments

Retrieves arguments passed to a dialogue box by #.CPro.Call or #.CPro.Make.

Syntax:

args←#.CPro.Args event_message

Run this action on the CR event on the form, so that it happens before the refresh of any other objects – these may well refer to local data passed as arguments!

CR:(name age sal)←∇Args ⍵

If no arguments have been passed, this returns a scalar zero.


CPro Turorial and Reference: #.CPro.Build

#.CPro.Build

Rebuild Internal Causeway Class Tables

This function must be run whenever you have added or removed classes, or changed the property list of an existing class.

Syntax:

#.CPro.Build

As it takes time to run (it parses all the class specifications) it should not be included in application initialisation code.


CPro Turorial and Reference: #.CPro.Call

#.CPro.Call

Modal Call of a Dialogue Box Definition

This makes and De-Queues a dialogue box, waiting for the user to respond.

Syntax:

{result}←{args} #.CPro.Call dbx_defn

The dialogue box appears immediately, in a local de-queue. This means that the user cannot interact with any other objects from the application until it is closed.

res←#.CPro.Call dbx.edit

The result from the call is normally either 1 (the user pressed OK) or 0 (the user pressed Cancel). However you can return any result you like by using #.CPro.Return in an action on any control on the form, for example on a ‘DoubleClick’ on a listbox ...

DC:∇Return index

This will return the value of index to the calling function on double-click.


CPro Turorial and Reference: #.CPro.Clear

#.CPro.Clear

Clear all Causeway and Class Working Tables

This returns the CPro namespace to an uninitialised state (all working variables are cleared) and it runs the Clear function in every class library on the current class path, and then in every class which has one. Typically, these would remove Gui objects (for example bitmaps) which were created when the classes were initialised.

Syntax:

#.CPro.Clear

This is called automatically by #.CPro.Reset.

This is a good function to run before saving the workspace after testing ...

)reset
#.CPro.Clear
)save

Hint: This may be a useful sequence to set up on a function key.


CPro Turorial and Reference: #.CPro.Do

#.CPro.Do

Running a Function from an Object

Runs any public function on an existing object.

Syntax:

res←obj #.CPro.Do ‘FunctionName’ args

The designer (right-mouse menu) will show you a full list of all the functions which a class supports. Many objects (such as the TreeView) have a large number of functions to enable you to add or remove items, roll-up or unroll the tree and so on. See the Function tables listed with each class for a full description.

To move the current cell of a grid to a given (r,c) index:

grid #.CPro.Do 'Move' (3 4)

The left argument may be the true name of the object (as here) or a group id. In this case the function is run on all the objects which have the group name included in their ‘Groups’ property...

'buttons' #.CPro.Do 'Hide'

... will hide all the objects in the ‘buttons’ group.


CPro Turorial and Reference: #.CPro.Execute

#.CPro.Execute

Run an APL Expression on any Form

This function enables an action on one form to run code on another form with access to local variables on the target form.

Syntax

res←obj #.CPro.Execute expr

The expression may refer to all variables which are in the scope of the target form and the form from which the action is run.

cost←form3 #.CPro.Execute '+/prices'

If the expression does not return a result, use #.CPro.ExecuteNR instead:

form3 #.CPro.ExecuteNR 'Optimiser'


CPro Turorial and Reference: #.CPro.Form

#.CPro.Form

Returns the Form to which a Control Belongs

To find the first parent of any control which has a ‘Locals’ property.

Syntax:

obj←#.CPro.Form obj

For example ...

parent←∇Form ⍺  ⍝ Current object
parent←#.CPro.Form obj

This should only be required for controls which have been added to nested structures such as status areas. Normally you can use #.CPro.Parent.


CPro Turorial and Reference: #.CPro.Forms

#.CPro.Forms

Returns All Current Forms

This is intended for use during development and debugging to allow the developer to use raw Dyalog code to explore the current Gui objects which are known to Causeway.

Syntax:

mat←#.CPro.Forms

For example ...

      #.CPro.Forms
'#.CPro.Class.Root.Control.FM44'  ⍝ Sample Form
'#.CPro.Class.Root.Control.FM66'  ⍝ Basic Form Functions

It returns a simple matrix. Each form is surrounded by quotes and has a trailing comment giving its caption. If this is echoed to the session it can easily by modified to get the children of the form, check on the event handlers etc.


CPro Turorial and Reference: #.CPro.GetContext

#.CPro.GetContext

Returns the Namespace where Form Actions Run

This utility function is intended for use by toolbar controls which may need to act on one of several MDI child forms or tabbed subforms, which may have been made in different namespaces. It can be used to find the correct namespace and switch into it.

Syntax:

ns←#.CPro.GetContext guiname

It returns a simple text vector, which will either be null (the Gui object was not found) or is a fully-qualified namespace path.


CPro Turorial and Reference: #.CPro.Id

#.CPro.Id

Finding an Object’s True Name

This returns the true (Dyalog Gui) name of all the objects which have this name included in their ‘Groups’ property.

Syntax:

obs←{parent}#.CPro.Id ‘groupname’

The name of an object can either be captured at create time:

CR: name←⍺

or retrieved later if we know its group id:

name←⊃#.CPro.Id 'grpname'

Note that more than one object can have the same id, hence the need to disclose the result if you only want one. #.CPro.Id looks in the current form by default – pass an object name as the optional left argument if you want to search a specific object for an id.


CPro Turorial and Reference: #.CPro.Init

#.CPro.Init

Setting Application Parameters

Sets the caption and icon for the entire application.

Syntax:

#.CPro.Init ‘Foreign Currency Trading’ ∆mainicon

The icon is optional – you will get the default ‘DyalogAPL’ icon if you omit this. Note that under Windows95 this is effectively obsolete as it is never shown in the task bar or the Alt+Tab dialogue.


CPro Turorial and Reference: #.CPro.It

#.CPro.It

Finding which Object has Focus

This returns the (fully qualified) name of the object which currently has input focus. It will be null if no current Causeway object qualifies.

Syntax:

obj←#.CPro.It

This will match exactly the name of the object which may have been captured at creation time, or which may be reported as a group member. It can be used in a toolbar action (such as Copy to Clipboard) to direct the action to the correct object.


CPro Turorial and Reference: #.CPro.IsAccelFree

#.CPro.IsAccelFree

Check if a given accelerator is free

Syntax

{fm} #.CPro.IsAccelFree ‘Ctrl+X’

This returns a boolean scalar indicating if that keycode in in use by the application. If {fm} is omitted, all forms are checked. Either the text form or the numeric keycode may be passed as argument.


CPro Turorial and Reference: #.CPro.ListAccelerators fm

#.CPro.ListAccelerators fm

List all current accelerators

This function returns a vector of accelerator keys (in standard format SHIFT+CTRL+D) to allow for checking or review. “fm” may be null, in which case all current accelerators are listed.

used←#.CPro.ListAccelerators ‘’


CPro Turorial and Reference: #.CPro.Make

#.CPro.Make

Non-modal Build of a Dialogue Box Definition

Creates a form from a dialogue definition matrix, populates all the controls with data, shows the form and returns to the calling function.

Syntax:

{objname}←{args}#.CPro.Make dbx_defn

This is used by the Designer to test out your forms (the ‘Run’ button) and is the normal call you would use during application development to allow you to write and test callback code.

#.CPro.Make dbx.main

The form will appear ready for use. You can continue to work in the APL session, make other forms etc. All event handlers will run normally, so this is the best way to run if you are developing application code around the actions on the form. It is also recommended for subsidiary dialogues where possible as the user can leave them open, and still return to the main form to continue work.

If you pass arguments, you can establish them as local variables on the form using #.CPro.Args. You may also record the name of the ‘Form’ object which is returned as the result.


CPro Turorial and Reference: #.CPro.MakeAsleep

#.CPro.MakeAsleep

Make a form without showing it or refreshing any controls.

Useful as a means of making ‘heavy’ dialogues in advance while the user expects a delay.

Syntax:

{objname}←{args}#.CPro.MakeAsleep dbx_defn

You can use #.CPro.Wake or #.CPro.Recall to refresh all the controls on the form and activate it as required.


CPro Turorial and Reference: #.CPro.Menu

#.CPro.Menu

Call a Popup Menu

This is called monadically to invoke a popup menu.

Syntax:

#.CPro.Menu menu_defn

You can use a standard CPro menu definition variable (with nested sections) or you can pass the menu on the fly, for example as the response to a mouse-down on an object:

MD: 2=3⊃⍵ : #.CPro.Menu 'Hello:2+2' 'World:var←3:var'

The chosen expression is executed and any variables in the ‘notify’ list (after the second colon) are hollered just as if you had listed them in the 4th column of a normal event-action table.

For simple menus, you might consider #.Win.Popup which is much faster, but only offers a simple, one-level, menu, or #.Win.PopupTree which can generate an open-ended tree structure of menus. These return the user’s selection, rather than executing a passed expression.

See also ...

Win.Popup – simple popup menu | Win.PopupTree – deep menu

Send comments on this topic
© Dyalog Ltd 2008


CPro Turorial and Reference: #.CPro.Notify

#.CPro.Notify

Broadcasting a Name which has Changed

Signals a change to a variable name from within application code.

Syntax:

{immed}#.CPro.Notify namelist

Any objects which have been set to listen to this name will be refreshed.

#.CPro.Notify 'age' 'salary'

Objects are notified on the all forms in the current scope. You might want to use this if you have a complex function running from an event-action table, and this must holler different variables depending on the path through the code.

Optional left argument of <1> causes immediate refresh, rather than the default which is to queue any updates. This could be used if you were in a local DeQueue (such as a locator or modal dialogue) but required immediately visible changes to an underlying form.

1 #.CPro.Notify 'colour'


CPro Turorial and Reference: #.CPro.Parent

#.CPro.Parent

Returns the Parent Control of any Object

To find the immediate parent of any Gui object.

Syntax:

obj←#.CPro.Parent obj

Normally this will be a form, or for a form it could be another form or a namespace. It is not necessarily the Gui parent as seen in the Dyadic name hierarchy, although for the majority of non-form objects this turns out to be the case.


CPro Turorial and Reference: #.CPro.Parse

#.CPro.Parse

Interpret Chart or Grid Specification

For compatibility with shareware Causeway, this is called by the Refresh function of the CH and TM/MA classes to interpret an editable specification such as:

     ↑spec
Cellwidths=23 44 76
Coltitles=One,Two
RowTitles=∆data

It will attempt to execute every phrase after the ‘=’ in each line, using the phrase itself if the execution fails. The phrase is always executed in the application namespace (i.e. where the CPro.Make/Call was run which built the initial form).

To see the effect, you can execute #.CPro.Parse with your data and pass this as the specification property to the Chart, TM etc.

     #.CPro.Parse spec
Cellwidths 23 44 76  Coltitles  One Two  RowTitles  This That Last

Note that if you use the text version of the specification, it is a good idea to check the ‘Always refresh property even if data is unchanged’ box in the designer as the expression may not have changed but the result of executing it might.


CPro Turorial and Reference: #.CPro.Post

#.CPro.Post

Sending Messages to Objects

Send an event message to an object.

Syntax:

{obj|group}#.CPro.Post message

The most common use is to close the main form from the File menu:

[File]
 &New: ....
 E&xit:∇Post 'SC'

The optional left argument is the id (as given in the group field of the behaviour table) or the true Gui name of an object – this can be used to close or minimise a floating toolbar from the main application:

'tbar' #.CPro.Post 'SC'

If you omit the argument, the message will be posted to the current object.

See the Event Reference for a full list of the event mnemonics.


CPro Turorial and Reference: #.CPro.Qna

#.CPro.Qna

Cover Common QuadNA Calls

This provides 16/32-bit covers for several standard ⎕NA calls. Check the function for the list, as more calls may be added after this documentation has been shipped.

For example to read a string ‘size’ from the general section of the ‘Appl.INI’ file ...

size←'gpps' #.CPro.Qna 'general' 'size' '120 200' 'appl.ini'

This will return 120 200 if the string is not found.


CPro Turorial and Reference: #.CPro.ReadNow

#.CPro.ReadNow

Forcing an Immediate Read

Forces an immediate read for a control (simple arg) or for a specific property of a control.

Syntax:

#.CPro.ReadNow obj [property name]

Typically this would be used on a text field with an accelerator, for example Ctrl+K to resolve names in Outlook98 style, which cannot see the data until the field gets a read event – which has not happened yet as the user has not tabbed out of the field.

An action on Select such as:

∇ReadNow ⍺ 'Text'

... will get the data variable updated with the current field contents. You can then follow this with the function which processes and perhaps updates the partial name with the resolved value.


CPro Turorial and Reference: #.CPro.Recall

#.CPro.Recall

Recalling Sleeping Forms

This wakes and de-queues a form which has previously been suspended with #.CPro.Sleep.

Syntax:

#.CPro.Recall obj

When a modal dialogue has been given a group id (which should be unique in this case), you can check that it still exists with:

fm←#.CPro.Id 'UID'

If fm is not empty, then you may recall the form:

CPro.Recall ⊃fm

Any controls which watch any data will be fully refreshed, then the form will be made visible. This process is virtually instant, and gives the user a much better perceived response. Here is a typical code fragment from a modal dialogue:

:If 0=⍴fm←CPro.Id'TOPIC'
   '.'#.CPro.Do'Wait'
   →(#.CPro.Call dbx.tpc)↓0
  :Else
   →(#.CPro.Recall⊃fm)↓0
 :End

This calls the form first time in (and sets a wait cursor as it may take time to build). Subsequent passes through the code just recall it, which is much faster.

If you need to do some processing when the form is recalled, you can use the WA (Wake-up call) event which Causeway will queue for you before the form becomes visible.


CPro Turorial and Reference: #.CPro.Reject

#.CPro.Reject

Rejecting an Event

Used to reject an event under program control.

Syntax:

#.CPro.Reject

Typically, this would be used in a validation rule to bounce invalid data. It may also be used to reject a ‘GetFocus’, which effectively makes a text field read-only.

If it is used in a set of actions, it terminates execution at this point – any lines of code below the rejection are not run, and no further names are hollered. Of course any code run (and names hollered) above the point of rejection remain changed.

It can also be used to reject a ‘System Close’ having offered the user a Yes/No/Cancel dialogue:

SC: 2=Win.Ync 'Save data?' : ∇Reject

Not all events can be rejected (for example MouseMove cannot be prevented).


CPro Turorial and Reference: #.CPro.Reset

#.CPro.Reset

Reset all Causeway Objects

This calls #.CPro.Clear to clear down all internal tables and classes, then initialises CPro and runs the ‘Initialise’ function for all class libraries and classes on the current class path.

Syntax:

#.CPro.Reset

This should be run whenever you need to clean up all outstanding forms, for example after a program crash when developing an application ...

→
#.CPro.Reset

Is a useful way to clear up prior to making the forms again.


CPro Turorial and Reference: #.CPro.Return

#.CPro.Return

Returning Data from Modal Forms

Sets the result returned from the #.CPro.Call of a modal dialogue and exits.

Syntax:

#.CPro.Return value

Sets the result of a #.CPro.Call and attempts to close the current form (it queues a SysClose message, so the user can still intervene here).

SL: ∇Return flag
DC: ∇Return chosen

Typically, this would be run on a Select (from an action button) or a DoubleClick on a list or combo object to confirm a selection and exit.

It may also be used in a menu, for example on the “[file]” menu ...

E&xit:∇Return 0

... will close the application (assuming the user agrees when offered an appropriate message).


CPro Turorial and Reference: #.CPro.SetClassPath

#.CPro.SetClassPath

Set Causeway’s Class Search Path

Sets the search path used by #.CPro.Build

Syntax:.

#.CPro.SetClassPath namelist

When you run #.CPro.Build to register all current classes, it searches for classes in all the namespaces listed in the current class path. By default, this is '#.Class', but you can use this function to modify the search ...

#.CPro.SetClassPath '#.MyClasses' '#.Class'

The earlier library has priority, so that to override a standard CPro class with your own (of the same name) you should put your library first in the list.


CPro Turorial and Reference: #.CPro.SetFocusTo

#.CPro.SetFocusTo

Move the Input Focus to any Control

Directs the input focus to any control.

Syntax:

#.CPro.SetFocusTo obj

This is often required when you exit from a modal dialogue to return the input focus to a sensible control on the parent form.

#.CPro.SetFocusTo editfield
&Options:∇Call dbx.options ⋄ ∇SetFocusTo 'LISTBOX'

You can pass either the Gui name of the object here, or a Group Id. If more than one control falls in the group, focus goes to one of them. The second line in the example shows how you might use this in a menu item.


CPro Turorial and Reference: #.CPro.Sleep

#.CPro.Sleep

Sending Forms to Sleep

Deactivates and hides any form.

Syntax:

#.CPro.Sleep obj

When you first call a modal dialogue, Causeway does a significant amount of processing to register all the controls so that the automatic refreshing of changed data works correctly. When the user closes the form, you can choose to hide it instead (turning off all refresh behaviour) by catching the Close Request event, deactivating the form, and rejecting the event:

CL: ∇Sleep ⍺ ⋄ ∇Reject

This will leave the form hidden, but with all the Causeway registration in place. To recall the form, you pass its object name to #.CPro.Recall which will refresh all the controls and make the form visible.

Note that if you send a form to sleep twice (for example by subsequently deactivating its parent) you must wake it twice!


CPro Turorial and Reference: #.CPro.UpdateAllChildren

#.CPro.UpdateAllChildren

Update All Children

This is a simple utility to force a full refresh of all the controls on a form.

Syntax:

#.CPro.UpdateAllChildren form

This could be used when new data had arrived (for example on File,Open) rather than notifying all the changed variables. The refresh is done for the current form and any child forms.


CPro Turorial and Reference: #.CPro.Wait

#.CPro.Wait

Waiting for User Input

Waits for user-input on all forms. Will continue when the last form is closed.

Syntax:

#.CPro.Wait

Normally, you would have a main form which generated any subsidiary forms from actions on tool buttons etc. These are automatically included in the Dyalog event queue as long as they are true ‘children’ of the main form. However this means that the original form is always beneath the children which is not always what you want (see MS Outlook where you can open a mail message but still show the main form). If you set the child forms to have the ‘TopLevel’ property true, they are free-floating forms, but you must ‘Make’ rather than ‘Call’ the main form, then use this function to wait for user input.


CPro Turorial and Reference: #.CPro.Wake

#.CPro.Wake

Wake a Sleeping Form

Reactivate a sleeping form.

Syntax:

#.CPro.Wake form

If #.CPro.Sleep has been used to hide/deactivate a non-modal form, you can use this function to revive it. The effect is to refresh all the controls, run the Wake function from the class (which would normally queue a WA (wake-up call) event) and make the form visible again.


CPro Turorial and Reference: #.CPro.Zap

#.CPro.Zap

Remove any Gui Object and Tidy the CPro Internal Tables

If you are testing an application which involves several forms, you may get application errors in some of the actions on a child form which leave you suspended in an SI stack. You can always clear CPro down completely with #.CPro.Reset, but if you simply want to back up one or two levels, and remove the forms which are no longer current:

Syntax:

#.CPro.Zap guiname

will ⎕EX the Gui object, having removed all the appropriate entries on the CPro internal tables. This will allow you a clean restart.

To find out the guiname, run #.CPro.Forms which will list all the current top-level objects in the seesion for you or add a ‘Create’ action to your form which simple echos ⍺ to the session for you.


Reference: The CPro Class Library

All the Gui classes supported by CPro are listed. You can easily build classes of your own, probably basing your work on one of these.

  • Action Button (AC)
  • Auto-filled Number (AFN)
  • Auto-filled Text (AFT)
  • Text Annotation (AN)
  • APL Text entry (APLTX)
  • Arc (captioned links) (ARC)
  • Backcloth (BK)
  • Bitmap Holder (BM)
  • Calendar (CAL)
  • Combo selector (CB)
  • Chart (RainPro graph) (CH)
  • Check Box Group (CK)
  • Close Button (CL)
  • Digital Counter (CT)
  • Drop-edit Combo (DC)
  • Date Entry (DT)
  • OK Button (EN)
  • Parent Form (FM)
  • Grooved Rectangle (GV)
  • Hidden Field (HD)
  • Time of Day (HM)
  • Help Button (HP)
  • Horizontal Splitter (HSB)
  • Horizontal Separator (HSEP)
  • Icon Holder (IC)
  • Image List (IL)
  • Label (LB)
  • Hyperlink (LBJ)
  • List Box (LS)
  • ListView (LV)
  • Numeric Matrix (MA)
  • MDI Child Form (MDI)
  • Most Recently Used (MRU)
  • Numeric Field (NM)
  • New-Open-Save-Exit (NOSE)
  • Notepad (NP)
  • Numeric Vector (NV)
  • Parameter Bar (PA)
  • Picture Button (PB)
  • Progress Indicator (PI)
  • Plinth or Recess (PL)
  • Poly Marker (PM)
  • PostScript Graphics (PS)
  • Polyline (PY)
  • Cancel Button (QT)
  • Radio Button Group (RB)
  • Containing Region (RGN)
  • RTF Editor (RTF)
  • Floating Palette (RU)
  • Status Area (Parent Region) (SA)
  • Scroll Bar (SB)
  • Status Field (SF)
  • Drop-down Selection (SL)
  • Spin Box (SP)
  • Status Bar (ST)
  • Subform (SUB)
  • Systray Item (SYS)
  • File Tabs (TAB)
  • Toolbar (TB)
  • Tool Control (TCTL)
  • Timer (TI)
  • Track Bar (TKB)
  • Tool Button (TL)
  • Text Matrix (Grid) (TM)
  • Tool Button – new style (TO)
  • TreeView (TR)
  • Tabbed Subform (TSF)
  • Text entry (TX)
  • VCR Buttons (VC)
  • Vertical Splitter (VSB)
  • Vertical Separator (VSEP)
  • Web Browser (WB)
  • Yes/No choice (YN)


CPro Turorial and Reference: Action Button (AC)

Action Button (AC)

Description

Normal push-button. Select should trigger its action.

The associated data may be a bitmap to place on the button. In this case, the caption must be left blank.

Use small bitmaps to make toolbar-style controls; 16 by 15 is a good size to put on a 20×20 button.

Generic functions Enable and Disable will grey out the bitmaps if necessary.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Tooltip | String |  |
Accelerator | String |  | Hotkey (e.g. Ctrl+S)
Style | ManyOf |  |
Caption | Runtime |  | Caption text
Bitmap | Runtime |  | Bitmap file name or bits array
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Auto-filled Number (AFN)

Auto-filled Number (AFN)

Description

Single-line text edit designed to help user enter a numeric code.

The lookup list is matched arithmetically, so must be unformatted, and therefore may not have leading zeros.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Value | User |  | Integer singleton
Lookup | Runtime |  | Lookup (integer vector)
Restrict | Bool |  | Limit text to list items
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help Request


CPro Turorial and Reference: Auto-filled Text (AFT)

Auto-filled Text (AFT)

Description

Single-line text edit. Text var is shown in the box and updated when the user leaves the field.

Lookup var may be set to a list of valid entries. As text is typed it ‘autocompletes’ to the nearest match. The user can continue to type – the entry is not restricted to the suggested list unless Restrict is set.

Pressing Alt+Down or the button opens a list-box to pick from. If a text matrix is given, the additional columns are shown in the drop-down as reference information for the user.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Text | User |  | Text to be shown in edit field
Lookup | Runtime |  | Lookup (text vectors or n-col matrix) to be matched
Case aware | Bool |  | Use case-sensitive matching
Restrict | Bool |  | Limit text to list items
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help Request


CPro Turorial and Reference: Text Annotation (AN)

Text Annotation (AN)

Description

Intended for small help panels and status boxes. The primary data should be a nested text vector with one element per paragraph. Each paragraph is wrapped into the object width.

It gets a recess as a frame, and is written with small dark-blue text. The user can clipboard text, and if necessary scroll around with the cursor keys (both optional).

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Text | Runtime |  | Panel contents
Selectable | Bool |  | Can the user ‘swipe’ the text?
Wrapping | Bool | 1 | Should the text be wrapped?


CPro Turorial and Reference: APL Text entry (APLTX)

APL Text entry (APLTX)

Description

Single-line APL edit. Text var is shown in the box in your APL font.

Defaults to stripping trailing blanks on field exit.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Text | User |  | Text variable (APL)
DTB | Bool | 1 | Delete trailing blanks

Class-specific Events

HR Help Request


CPro Turorial and Reference: Arc (captioned links) (ARC)

Arc (captioned links) (ARC)

Description

Multiple arcs for use in joining nodes on network diagrams.

Optional caption, which defaults to the centre point of the arc. Bigger numbers in the ‘Caption bias’ will move it towards the target end of the arc in the ratio n:1.

Style may be: Colour (0-15) [Weight,Style,Caption Bias]

From-To is (n × 4) matrix of end-points or (n × 5) matrix with text captions as the 5th column.

To set individual styles for each segment, enclose the required element, for example to set individual colours, but all arcs 2 pixels thick:

Format: (3 3 4 5 4 3) 2

Note that the colour vector MUST match the number of arcs.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
From-To | Runtime |  | From-To matrix (r c r c [txt])
Format | Runtime |  | Colour (0-15) [Weight,Style,Caption bias]


CPro Turorial and Reference: Backcloth (BK)

Backcloth (BK)

Description

Backcloth may be used passively to display a bitmap behind other controls (e.g. a drawing of plant configuration behind a plant control system). In this case, it would need the data variable only, probably giving the ‘name’ of a bitmap file.

Use 1 (=Tile) to make nice backgrounds, such as a grooved playing surface for a chess game.

A more active use would be to make a bitmap display where the mouse could be used to pick selected bits. When you select 2 (=Stretch) the co-ordinate system of the Backcloth is set automatically to match the bit pattern. Mouse actions are then reported as the (QuadIO+) bit position.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Picture | Runtime |  | Bits array
Placement | Runtime |  | Place (0=TopLeft; 1=Tile; 2=Stretch; 3=Centre)


CPro Turorial and Reference: Bitmap Holder (BM)

Bitmap Holder (BM)

Description

Used to place a bitmap anywhere on your form. It shows in the designer as a 32×32 pixel outline, but actually has no defined size. The bitmap will be placed with the top-left corner at the position of the placeholder.

Reference is an array of bits (numbers 0..15) or the name of a .BMP file (in quotes). Use the style to set framing options, which are: {none; Recess; Plinth; Cutout}.

Uses global #.Class.∆cmap to force a standard 16-colour mapping.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Bits | Runtime |  | Bits array or ‘file name’


CPro Turorial and Reference: Calendar (CAL)

Calendar (CAL)

Description

Adds a Windows-95 calendar to your form. This is a very thin cover on the standard Dyalog class – check your Dyalog help file for full details! More properties may be added in future versions.

Note that for compatibility with the Causeway Date class you can switch to using Excel-coded dates which are one day different from March 1900 onwards.

Class Property Table

Name | Type | Default | Description
HasToday | Bool | 1 | Is Today’s data displayed?
CircleToday | Bool | 1 | Is Today circled on the calendar?
WkNumbers | Bool | 0 | Include week numbers to the left?
MaxDays | Int | 1 | Max number of days to select
Date | User |  | Selected Date(s) (integer day numbers)
BoldDays | Runtime |  | Integer vector of dates to be shown as bold
Encoding | OneOf | ‘Dyalog’ | Compatibility mode (Dyalog or Excel)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Combo selector (CB)

Combo selector (CB)

Description

Used to select from a large list of names (in alphabetical order – see the Search dialogue in Windows 3.1 help). You can click to select, or type in the leading letters to scroll the list quickly to the first name beginning with those letters.

Text – should be a simple text vector (typically starts null).

Items – is an alphabetic list (nested vector).

On pressing <Enter> with a partial entry, the combo completes it for you and selects it. A further <Enter> confirms this, and is passed on to the <OK> button to close the dialogue.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Text | User |  | Text variable (text)
Items | Runtime |  | Items List (should be alphabetic)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Chart (RainPro graph) (CH)

Chart (RainPro graph) (CH)

Description

Basic Interface to the RainPro Graphics Interpreter

Uses a simplified set of the Rain charting language to build standard business graphics in a given drawing space.

Double-click redraws the chart at full-screen size, and enables printing, cursor tracking etc.

See the RainPro documentation for the syntax of the chart specification.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Data | Runtime |  | Data to chart (numeric array)
Format | Runtime |  | Chart specification
Heading | Runtime |  | Chart Heading (text, delimited by ‘;’)
ChartPath | txt | ‘#.ch’ | Path to RainPro namespace
PSPath | txt | ‘#.PostScrp’ | Path to PostScript namespace

Class-specific Events

COBJ | Chart Object clicked
CDATA | Chart Data clicked

Class-specific Functions

Clipboard | Copy chart to clipboard
Print | Print chart to default Printer
WriteEPS | Save chart as Encapsulated PostScript file


CPro Turorial and Reference: Chart (RainPro graph) - COBJ Event

Chart (RainPro graph) – COBJ Event

This event is reported when you release the mouse over a chart object such as a heading or caption. The event message is a 3-element vector giving:

  1. Chart id – a unique name for the chart such as chart98562. This may be supplied by the application using ch.Name or it will have been generated by RainPro.
  2. Object type – one of ‘Heading’ ‘YCaption’ ‘XCaption’ etc. See the RainPro documentation for the complete list.
  3. Gui name – the internal Dyalog name for the object.

You may use the Dyalog name to modify the object directly, or call #.PostScrp.SetObject with the Chart id, the Object type, and the new value for the object.


CPro Turorial and Reference: Chart (RainPro graph) - CDATA Event

Chart (RainPro graph) – CDATA Event

This event is reported when you release the mouse over a data point such as a marker, a bar or a pie wedge. The event message is reported as a 4-element vector giving:

  1. Chart id – a unique name for the chart, which may be given by the application using ch.Name when you draw the chart.
  2. Series id – a name for the data series, which will be null unless supplied by the application using ch.Series.
  3. Row,Column – the row,column index in the data matrix of the data point. This is always reported in ⎕IO=1. Vectors are treated as 1-column matrices, and always report the column dimension as 1.

Note that if you want to use this event but draw with lines only, you can use the ‘invisible’ marker style to get the hotspots marked for you.


CPro Turorial and Reference: Chart (RainPro graph) - WriteEPS Function

Chart (RainPro graph) – WriteEPS Function

This takes a file name and generates a standard ‘Encapsulated PostScript’ file for inclusion in any DTP software such as MS Publisher or MS Word.

  cht ∇Do 'WriteEPS' 'C:\temp\test.eps'

Note that Word cannot show the chart on screen – you will see a rectangle of the correct size with the chart title, date and time etc. It will print correctly on a PostScript printer. If you need to print charts to a standard Windows printer, use the Clipboard function instead and paste the chart into your document.


CPro Turorial and Reference: Check Box Group (CK)

Check Box Group (CK)

Description

This makes a group of check buttons, with the caption as the group tag (which may contain &Accelerators). You can choose whether to work with a boolean vector (one element per label) or a vector of indices to the checked entries. Do not add expressions for both the Indices and Checked properties!

The buttons are spaced out evenly within the object size and are re-arranged if the object is resized by the user.

Labels is a matrix of button captions. A vector is treated as a one-column matrix so that the group is arranged vertically. Otherwise the shape sets the layout of the buttons. Note that the Indices property will be the index into the ravel of this matrix.

Level The effect of a level vector is to provide indenting of the checkboxes, and also to disable any logical children of unchecked parents. This can be used where some selections are only valid when the parent has been chosen.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Indices | User |  | Indices variable (selected indices)
Checked | User |  | Boolean vector (checked boxes)
Labels | Runtime |  | Labels List (button labels)
Level | Runtime |  | Depth vector for indented look
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Close Button (CL)

Close Button (CL)

Description

Just an Action Button which sends a ‘System Close’ to its parent form on Select. Use this to end non-modal forms or your main application window.

Note that you can catch the ‘Close Request’ on the main form, and reject it from here, or offer to save data before leaving the application.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |


CPro Turorial and Reference: Digital Counter (CT)

Digital Counter (CT)

Description

Minesweeper look-alike!

Useful for a running timer, or any kind of ‘score’ object. Default is a three-digit field, in red.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Value | User |  | Value (Integer Singleton)
Digits | Runtime |  | Digits to show [,colour index]


CPro Turorial and Reference: Drop-edit Combo (DC)

Drop-edit Combo (DC)

Description

Used to select from a large list of names (generally in alphabetical order). You can click to select, or type in the leading letters to scroll the list quickly to the first name beginning with those letters. The text is not restricted to the entries in the lookup list.

Text – should be a simple text vector (typically starts null).

Lookup – is an alphabetic list (nested vector).

On pressing <Enter> with a partial entry, the combo completes it for you and selects it. A further <Enter> confirms this, and is passed on to the <OK> button to close the dialogue.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Text | User |  | Text variable (text)
Lookup | Runtime |  | Lookup List (alphabetic)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Date Entry (DT)

Date Entry (DT)

Description

Edit field which expects and assigns dates as numeric scalars. The appearance is picked up from WIN.INI, so formatting information is optional. It operates a simple ‘moving window’ around the century change if you use 2-digit years.

The field has a simple ‘spin’ behaviour, which increments the days, and kicks over the months when required. The string ‘t[oday]’ is acceptable; also the field defaults to {current} when month or year are omitted.

Dates are held as the elapsed days, with 01/01/1900 as day-1. This is the same scheme as Dyalog uses, and allows easy addition and subtraction of dates. Note that 29-1-1900 is NOT a leap year (unlike the Excel bug unless you switch to Excel mode).

Pressing <Enter> with a partial date re-displays it in its complete form. A further <Enter> confirms, and is passed through to the <OK> button if there is one.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Date | User |  | Date variable (integer date)
Picture | Runtime |  | Date picture (e.g. ‘dd-m-yyyy’)
Encoding | OneOf | ‘Dyalog’ | Compatibility mode (Dyalog or Excel)
Delay | Int | 400 | Initial delay (ms)
Interval | Int | 50 | Repeat interval (ms)
Tracking | Bool | 1 | Update data every click
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Functions

DayofWeek | Returns day of week as 3-element text given ordinal date
SetWindow | Set sliding date window (cf 1st element of yy_window)


CPro Turorial and Reference: Date Entry - SetWindow Function

Date Entry – SetWindow Function

The CPro DT class supports a simple sliding window. The number you give is the number of years before the current date which should be left as entered by the user. Dates older than this automatically have 100 years added.

You might like to set this to be the same as the absolute value of the first element of yy_window for consistency with grid dates.


CPro Turorial and Reference: OK Button (EN)

OK Button (EN)

Description

Just a button, with ‘Default’ set. Returns 1 from the form call when pressed. In multi-form systems use a “Close” button instead.

Note that if you run an expression on “Select” you will need to include the default action ∇Return 1 for the form to close.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |


CPro Turorial and Reference: Parent Form (FM)

Parent Form (FM)

Description

This is the normal starting point for an application or simple dialogue box. Styles can be used to get special effects, such as ‘Banner’ for welcome screens.

Caption – is simply the title bar. You can also use the Titlebar property.

Style – might be ‘Dbx’ for dialogue boxes

Titlebar – resets the form titlebar if used, typically on loading a new file.

Menu – is a Menu Structure which is used to build the menu for the form

To intercept a user’s request to close the form, use an action on the ‘CL=Close Request’. If this returns zero, the form will not close.

Class Property Table

Name | Type | Default | Description
Locals | NameList |  | Local variables
Style | ManyOf |  |
Centred | Bool |  | Centre on screen
TopLevel | Bool |  | Made as a top-level form
Minsize | Numlist | ⍬ | Minimum size (height,width) in pixels
Titlebar | Runtime |  | Form Titlebar (text vector)
Menu | Runtime |  | Menu structure
Artwork | Runtime |  | For menu images (16×16n integer array of bitmap data)
Topform | User |  | Active MDI or Tabbed child

Class-specific Events

PC | Post-Create
NM | New Menu
WA | Wake-up Call
CL | Close Request

Class-specific Functions

Check | Tick named menuitem
Uncheck | Uncheck named menuitem
IsChecked | Report if menu items with this id are checked
IsEnabled | Report if menu items with this id are enabled
Id | Return the Gui names of all menu items with this id
SetMenuCap | Reset menu caption(s) of matching items
SetMenuImages | Set image indexes for one or more named menu items
Maximize | Maximize form
Minimize | Iconise form
Restore | Return to normal
Cascade | MDI cascade
Arrange | MDI icon arrange
Htile | MDI Horizontal Tile
Vtile | MDI Vertical Tile
SetIcon | Set System/Minimised Icon
Tips | Turn ‘bubble help’ off/on
Wait | Show hourglass (Wait 1 disables all controls)
Ready | Cancel wait


CPro Turorial and Reference: Parent Form - TopLevel Property

Parent Form – TopLevel Property

Normally, forms made from actions on other forms are created as ‘children’ which means that they always come on top of the parent form. If you set this property to ‘True’ you will be able to move the parent form over the child. Note that you must ‘Make’ rather than ‘Call’ the parent here and use CPro.Wait to have it respond to events.


CPro Turorial and Reference: Parent Form - PC Event

Parent Form – PC Event

This event is queued to the form after the completion of the first refresh. It is a workaround to allow you to make toolbars, status areas etc after the menu has been added (by the Refresh function) but before the form becomes visible. This way, Dyalog draws them right!

PC : ∇Make dbx.tbar


CPro Turorial and Reference: Parent Form - NM Event

Parent Form – NM Event

This is signalled to the Form whenever its menu property is updated by Causeway as the result of a change to the menu variable. It may be used for some post-processing, for example to check or grey out known items:

NM : ⍺ ∇Do 'Check' 'option5'


CPro Turorial and Reference: Parent Form - WA Event

Parent Form – WA Event

This is queued after a sleeping form has been woken (see #.CPro.Wake) or recalled (see #.CPro.Recall), but before any data expressions are run or it becomes visible. If an argument is passed to Wake or Recall, the argument value may be recovered in the same way as for the standard Create event:

WA : (year product)←⍵

These new local variables will then be used to refresh any data fields on the form.


CPro Turorial and Reference: Parent Form - CL Event

Parent Form – CL Event

The Close Request is to offer the user a chance to intercede and either save data or reject the close. See Close Request Event for details.


CPro Turorial and Reference: Parent Form - Check Function

Parent Form – Check Function

Used on the main form to add a check mark to any named menu item. The argument gives the group name – all menu items which include this name in their groups list will be checked.

⍺ ∇Do 'Check' 'BOLD'  ⍝ When bold selected

See also: Menus; Uncheck


CPro Turorial and Reference: Parent Form - Uncheck Function

Parent Form – Uncheck Function

Removes the checkmark from a previously checked menu item (identified by the group name).

fm #.CPro.Do 'Uncheck' 'Italic'  ⍝ Italic deselected

See also: Menus; Check command


CPro Turorial and Reference: Parent Form - SetMenuCap Function

Parent Form – SetMenuCap Function

Allows an application to reset a menu caption (and optionally the accelerator) on the fly.

fm #.CPro.Do 'SetMenuCap' 'COPY' '&Reproduce=Ctrl+R'

This sets the caption of all menu items entries matching the group id ‘COPY’ (usually there will only be one) to ‘Reproduce’ and resets the accelerator key to Ctrl+R. If you omit the ‘=key’ portion, the existing accelerator remains in force.


CPro Turorial and Reference: Parent Form - SetMenuImages Function

Parent Form – SetMenuImages Function

If the ‘artwork’ property is set on the form, you can use this function on a PostCreate action to set the image index for any menu items which require associated pictures:

PC :⍺ ∇Do 'SetMenuImages' mat

This expects an n × 2 matrix of menu item IDs and integers (in your ⎕IO) giving the image to be associated with each item (or submenu). Note that if you reset the menu dynamically you will need to re-apply the function above to regenerate the images. To apply the same image to more than one item you will need to give it a different ID and use the same index number for both.

To set an image for a menu, use its existing name, but enclosed in [] as it appears in the menu definition. A valid matrix of menu settings could be ...

    NEW      6
    OPEN     7
    SAVE     8
    THIS    13
    [next]  14


CPro Turorial and Reference: Parent Form - SetIcon Function

Parent Form – SetIcon Function

Usually called on the Create event to set the form icon (best drawn 16 by 16 under Windows 95) to either a filename or a numeric matrix giving colours and transparancy:

CR : ⍺ ∇Do 'SetIcon' (16 16⍴⍳4)


CPro Turorial and Reference: Parent Form - Tips Function

Parent Form – Tips Function

This switches pop-up tips on/off for all the controls on this form. By default, tips are on. You might pick up a user’s preference from an INI file and use this when the form is created:

CR : ⍺ ∇Do 'Tips' (GetPref 'tips')


CPro Turorial and Reference: Parent Form - Wait Function

Parent Form – Wait Function

In the simple case, this just shows the ‘hourglass’ cursor. This discourages the user from pressing buttons, but does not actually prevent it. If you have a long process to run, you can disable all the controls on the form (and on all child forms) with a button action such as:

SL : (∇Parent ⍺) ∇Do 'Wait' 1 ⋄ LongProcess
    (∇Parent ⍺) ∇Do 'Ready'

This will stop the user mistakenly pressing the button again!


CPro Turorial and Reference: Grooved Rectangle (GV)

Grooved Rectangle (GV)

Description

Decorator used to frame clusters of buttons etc. Defaults to 1-pixel, but data variable sets the depth. 2 is the maximum that works at all well. Negative numbers give ridges. Only -1 is really recommended here!

Note that grooves can have captions but NOT hints (Dyalog limitation).

Class Property Table

Name | Type | Default | Description
Style | ManyOf |  |
Depth | Runtime |  | Depth (negatives give ridges)


CPro Turorial and Reference: Hidden Field (HD)

Hidden Field (HD)

Description

Hidden label to allow ‘hot keys’ to trigger actions from invisible objects. May also be used to hook a Pre-Refresh handler on to any APL array, thus triggering arbitrary processing when some data value changes.

Class Property Table

Name | Type | Default | Description
Accelerator | txt |  | Accelerator key
Data | Runtime |  | Any APL array


CPro Turorial and Reference: Time of Day (HM)

Time of Day (HM)

Description

Edit field which expects and assigns times as numeric scalars, represented as the decimal part of the day, i.e. 12:00 would be 0.5. This is compatible with Excel, and allows you to add times to dates easily.

The field has a simple ‘spin’ behaviour, which increments the minutes, and kicks over the hours when required. You can set the increment (e.g. to 60) to spin in appropriate units. To turn off normal CPro refresh during spinning, set Tracking=0.

If a single number is entered, it is taken as hours, on a 24-hr clock. The characters ‘N’ and ‘n’ are acceptable as ‘Now’.

Pressing <Enter> with a partial time redisplays it in its complete form. A further <Enter> confirms, and is passed through to the <OK> button if there is one.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Time | User |  | Time (decimal day from 00:00)
Increment | Runtime |  | Increment in minutes (default 1)
Delay | Int | 400 | Initial spin delay (ms)
Interval | Int | 50 | Spin repeat interval (ms)
Tracking | Bool | 1 | Update data every click
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Help Button (HP)

Help Button (HP)

Description

Appears as a normal push button, typically captioned ‘&Help’.

Intended to be used in dialogue boxes to invoke context-sensitive help. It pays to be fairly structured about assigning context numbers to your help topics, then you can use these numbers to enter the help file at the appropriate topic.

Will invoke the help file at its ‘Contents’ page if no context or keyword is given. If there is more than one occurrence of a keyword, the help file will open at the first reference to it.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Accelerator | String |  | Hotkey (e.g. F1)
Style | ManyOf |  |
Topic | Runtime |  | Help Context number or ‘keyword’
File | Runtime |  | Help ‘file name’


CPro Turorial and Reference: Horizontal Splitter (HSB)

Horizontal Splitter (HSB)

Description

Emulates a horizontal separator by resizing the objects above and below. Takes the group ids of all the objects you want it to manage (any order). This could (for example) be used to separate two grids in a simple emulation of Excel’s split window.

You will probably need to experiment with the finished dialogue to set the limits correctly. Normally you should restrain the splitter from squeezing a control completely down to zero size.

Class Property Table

Name | Type | Default | Description
Controls | Stringlist |  | Objects to split (group ids)
Hidden | Bool |  | Used to constrain other splitters
Limits | Runtime |  | Closest Approach to edge (top,bottom)
Where | User |  | Current vertical position

Class-specific Functions

MoveTo Move splitter to this row (pixel position)


CPro Turorial and Reference: Horizontal Separator (HSEP)

Horizontal Separator (HSEP)

Description

Simple ruled line to segregate controls. Constrained to a horizontal line – use VSEP for verticals.

Class Property Table

Name | Type | Default | Description
3D | OneOf |  | How drawn (groove or ridge)


CPro Turorial and Reference: Icon Holder (IC)

Icon Holder (IC)

Description

Used to place a captioned icon on a form. The Icon variable can be an array of bits (16-colour) or the name of a .ICO file (in quotes).

To get transparency, the var should be shaped [2;32;32] where the second plane is 1 for ‘transparent’, 0 for ‘solid’. Two-dimensional arrays are acceptable, but are shown solid.

The caption is written centred underneath in small text. It will be wrapped so as to make each wrapped line approximately the same length.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Icon | Runtime |  | Bits array or ‘file name’


CPro Turorial and Reference: Image List (IL)

Image List (IL)

Description

Creates an imagelist for use by trees and list-view controls. Make sure it is in the tab-order before any control that uses it!

Icons – a vector of icon names (simple vector acceptable).

IconSize – required size (larger icons are scaled).

Masked – set this to 0 for solid colour artwork

SeeThru – use to switch the transparent colour from light grey

Assign its name on CR then use this as argument to the SetImage function on either the Tree or the ListView. Note that you will need 2 separate lists at different sizes if you need to show both ‘Icon’ and ‘Small Icon’ views in the listview.

You can use external icon objects (xx.ICO files), or it may be more convenient to make a bitstrip in the workspace using the picture editor in which case the default is to use light grey as the transparent colour. If your icons use grey as a genuine colour, you might like to set the SeeThru colour to 13 (bright pink) and use this to mark the transparent areas.

Class Property Table

Name | Type | Default | Description
Icons | Runtime |  | Vector of Icon names
IconSize | Int | 16 | Scale icons to this size
Masked | Bool | 1 | Make transparent images
SeeThru | Int | 8 | Colour used as transparent in bitmaps


CPro Turorial and Reference: Label (LB)

Label (LB)

Description

Text label. Shows its normal caption, or its data variable if set.

Special styles (best used with ‘Smalltext’):

- ‘Recess’ which is handy for status line messages.

- ‘Plinth’ looks good as column headers

Font, Emphasis and Pointsize can be used to add fancy effects.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Caption | Runtime |  | Label value
Colour | OneOf | ‘Black’ | Line colour
Font | OneOf | ‘(any)’ | All installed fonts
Emphasis | OneOf | ‘(none)’ | Bold, italic etc.
Pointsize | Int | 12 | Font Size in points


CPro Turorial and Reference: Hyperlink (LBJ)

Hyperlink (LBJ)

Description

Text label which acts as a hyperlink to a web page.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Target | Text |  | Jump target
Colour | OneOf | ‘Deep blue’ | Label colour
Caption | Runtime |  | Update design-time caption and jump target

Class-specific Events

RBM Right-mouse menu


CPro Turorial and Reference: Hyperlink - RBM Event

Hyperlink – RBM Event

Right-mouse menu event is passed the target hyperlink as the event message.


CPro Turorial and Reference: List Box (LS)

List Box (LS)

Description

Simple multiple selection from a scrolling list. You can choose between an index vector or a boolean mask as the most convenient way of representing your data as the selected items.

Indices – should be an integer vector of indices into Items

Selection – a boolean mask on Items (length should match Items)

Items – which is the text shown in the box (Nested text vector)

Caption (if used) makes a label directly above the list. Note the ‘toggle’ style which simulates <Ctrl> being held and the ‘multicolumn’ style which is good for long lists of short names.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Select | OneOf | ‘Multi’ | Selection strategy (‘Single’ ‘Multi’)
Style | ManyOf |  |
Items | Runtime |  | Items List (listbox contents)
Indices | User |  | Integer vector (selected indices)
Selection | User |  | Boolean vector (length equal to items)
FirstRow | User |  | First visible row
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Functions

SetTabs set tabs at distance(s) in pixels from left edge of listbox


CPro Turorial and Reference: List Box - SetTabs Function

List Box – SetTabs Function

Sets the tab stops in pixels. To make a columnar list, insert tab characters (⎕AV[⎕IO+9]) into the items in the item list. By default, tab stops are positioned at 8-character boundaries (measured using 8⍴'0').

 CR : ⍺ ∇Do 'SetTabs' 96 200


CPro Turorial and Reference: ListView (LV)

ListView (LV)

Description

Simple multiple selection from a Windows95 list view.

Indices – should an integer vector if indices into ...

Items – which is the text shown in the box. (Nested vector or matrix).

Checked – adds a selector column 0=off 1=on 2=locked on

If icons are required, Items can be a 2-column matrix, giving the items in column-2 and the image index in column 1. Extra columns specify the columns to the right when the list is in report view. Styles ‘gridlines’ and ‘full row select’ may be used here.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
3D | OneOf | ‘Recess’ | Border style
Items | User |  | Items (vtv or n-col matrix)
Indices | User |  | Selected indices
Selection | User |  | Boolean vector (length equal to items)
Checked | User |  | Option settings 0-2 = off/on/locked
ImageIndex | Runtime |  | Index to icon (if not given in Items)
ColTitles | Runtime |  | Column titles in report view (vtv)
View | Runtime |  | View (‘Icon’ ‘SmallIcon’ ‘List’ ‘Report’)
Select | OneOf | ‘Multi’ | Selection strategy (‘Single’ ‘Multi’)
DragSource | Bool |  | User can drag items off this control
DragMode | OneOf |  | Permitted drag operations
DropAccept | StringList |  | Accepts drag-over and drag-drop from these groups
Editable | Bool |  | Item labels may be edited by the user
ApplData | User |  | Application data (matrix)

Class-specific Events

CC | Column Clicked
IDC | Item double-clicked
IDG | Item dragged
PC | PostCreate
DRAGOFF | Item dragged off the list
DRAGOVER | Item dragged over the list
DRAGDROP | Item dropped on the list
CONFM | User pressed enter
EDIT | User changed label text
HR | User pressed F1
RMM | Right-mouse menu request

Class-specific Functions

ColTitleAlign | arg is a vector ‘Left’ ‘Right’ ‘Left’ ... etc
GetColWidth | gets the column width (pixels); arg is column no(s).
SetColWidth | sets the column width im[;column, pixels]
SetColWidths | sets the leftmost column(s) in one call
SetImage | takes the name of one or two existing imagelist (IL) objects
SetView | arg can be ‘icon’ ‘smallicon’ ‘list’ ‘report’ (1st letter only reqd)
Sort | sorts contents according to user-supplied array
SortByColumn | sorts contents according to specified column


CPro Turorial and Reference: ListView - DragSource Property

ListView – DragSource Property

If this property is set to ‘true’ you will be able to drag items off the list. You may wish to handle the DRAGOFF message which you can reject if it is not appropriate to drag this particular item.


CPro Turorial and Reference: ListView - DropAccept Property

ListView – DropAccept Property

This property sets the list of group ids from which the listview will accept drag-drops. You can set it to ‘*’ to accept dropped items from any control, including itself. Even if you accept items from a control, you can handle the DRAGOVER and DRAGDROP messages to selectively ignore particular items, or to reject drops on specific elements of this control.


CPro Turorial and Reference: ListView - CC Event

ListView – CC Event

Signalled by the ListView control when in ‘Report’ view.

The message gives the column number of the header block which was clicked. This could be used to sort the data by the selected column, or initiate a ‘Find’ dialogue.

CC : ⍺ ∇Do 'SortByColumn' (⊃⍵)


CPro Turorial and Reference: ListView - DRAGOFF Event

ListView – DRAGOFF Event

Signalled only if the list is set as a drag-source and the user has dragged the mouse on an item to pick it up. The message gives the ‘SelItems’ currently in the list. You may reject the event if it is not appropriate to pick up this particular item, or you may re-assign ⍵ to insert your own token and information here.


CPro Turorial and Reference: ListView - DRAGOVER Event

ListView – DRAGOVER Event

Reported when the listview has at least one group in its ‘DropAccept’ list and an item from this source is being dragged over it. The message reports (item-index in your ⎕IO)(mode)(menu)(token from drag source)(group1 of source)(group2 ...) as an n-element vector. In the message, mode is 0 for move, 1 for copy; menu is 0 for a normal drop, 1 for a menu request (right-button drag). You may reject the event – otherwise the list item will be drop-highlighted.


CPro Turorial and Reference: ListView - DRAGDROP Event

ListView – DRAGDROP Event

Reported when the listview has at least one group in its ‘DropAccept’ list and an item from this source is dropped on it. The message reports (item-index)(mode)(menu)(token from drag source)(group1 of source)(group2 ...) as an n-element vector. You may ignore the event, but not reject it or modify the message format.


CPro Turorial and Reference: ListView - EDIT Event

ListView – EDIT Event

Reported when the text of a label has been changed by the user. The message has the item number and new text as a 2-element vector. If you reject the message, the change will not be accepted by the control.


CPro Turorial and Reference: ListView - RMM Event

ListView – RMM Event

Reported when the right-mouse button is released over an item, with the mouse having been moved less than the distance needed to initiate dragging. The message reports the item-index.


CPro Turorial and Reference: ListView - ColTitleAlign Function

ListView – ColTitleAlign Function

Aligns the titles and data in each column of a ListView control. The effect is visible only in Report view.

CR: ⍺ ∇Do 'ColTitleAlign' strs

where strs is a text vector or vector of text vectors, one item per column. Each item must be one of 'Left' 'Centre' 'Center' 'Right'. The items can be uppercase or lowercase. Any unrecognised item is treated as ‘Left’.

The leftmost column of the ListView control is always left-aligned regardless of the value of the first item. If the right argument contains more items than there are data columns, the rightmost unused alignment values are stored. They take effect if additional columns of data are added to the ListView.


CPro Turorial and Reference: ListView - GetColWidth Function

ListView – GetColWidth Function

Returns the width, in pixels, of one or more columns of a ListView control.

CR : ⍺ ∇Do 'GetColWidth' inx

where inx is an integer scalar or vector, the column number(s) of interest.

The result is an integer scalar or vector. Each value is the width, in pixels, of the corresponding column in the right argument. The number of items in the result is also a function of the current value of the View property of the ListView control:

View | Description
Icon | The result is an empty vector. There is no column width in this view.
SmallIcon | The result is an empty vector. There is no column width in this view.
List | The result is a one-element vector. There is only one column in this view. The value of the right argument is treated as if it is ⎕IO.
Report | The result contains one element for each item in the right argument. The width of the rightmost data column in the ListView is returned for any column index that lies outside of the range of data columns.


CPro Turorial and Reference: ListView - SetColWidth Function

ListView – SetColWidth Function

Sets the width, in pixels, of one or more columns in a ListView control.

CR: ⍺ ∇Do 'SetColWidth' widths

where widths is a two-element vector or a two-column matrix with one row per column. Each pair of items is the column index number and its width in pixels, respectively.

If the current value of the View property is 'Icon' or 'SmallIcon', this command has no effect. The control has only one column if the View property is 'List'. In this case, SetColWidth takes the value of the first column width in the right argument and applies it to this column. This value must be an integer value greater than zero.

If the View property is 'Report', the width can be a positive integer value or one of three special values:

¯1 | resizes to the default column width of 100 pixels
¯2 | resizes to fit the data in the column, including the column title
¯3 | same as ¯2 except when applied to the rightmost column, which is extended to the right-hand edge of the ListView control if there is sufficient space to fit the data in the column, i.e., the space available for the column exceeds the width needed to fit the data.

The column widths in the 'List' view are entirely independent of the column width in the 'Report' view.


CPro Turorial and Reference: ListView - SetColWidths Function

ListView – SetColWidths Function

Takes a vector of required widths (in pixels) and applies them successively from the left, using the same rules as defined for SetColWidth.


CPro Turorial and Reference: ListView - SetImage Function

ListView – SetImage Function

Sets the ImageList property of the ListView, which must name an existing ImageList object. If you give this a single imagelist, the images are used in all views. You can also give two lists, and the ListView will use the second in all views except ‘Large Icon’. Clearly, this is best made of 16×16 icons!

CR : ⍺ ∇Do 'SetImage' largeicons smallicons

In this case, you should use the Object Sorter in the designer to ensure that both ImageList objects come before any ListView objects which refer to them.


CPro Turorial and Reference: ListView - SetView Function

ListView – SetView Function

Sets the appearance of the ListView.

lv ∇Do 'SetView' view'

where view is a text scalar or text vector, (the first character of) one of 'Icon' 'SmallIcon' 'List' 'Report'. Any other value implies 'Icon'. The case of the argument is ignored.


CPro Turorial and Reference: ListView - Sort Function

ListView – Sort Function

Re-orders the contents of the ListView according to a supplied sort vector.

lv ∇Do 'Sort' order

where order is an integer vector, a permutation of ⍳n where n is the number of items in the control.

The result is an integer scalar, 0 if control properties were sorted, >0 if an error condition was detected.


CPro Turorial and Reference: ListView - SortByColumn Function

ListView – SortByColumn Function

Re-orders the ListView according to the sort order of the values in a specified column.

lv ∇Do 'SortByColumn' col

where col is an integer scalar, either a column number or the special case value ¯1.

When sorting according to the values in a specific column, the sort is always in ascending order the first time a column is selected. If the same column number is used in a sequence of calls to SortByColumn, the sort order alternates between ascending and descending on successive calls.

The ListView can be re-ordered according to any column in the Items or ApplData properties. The ApplData property, if it exists, is treated as if it is laminated along the last axis of the Items property (i.e., Items,ApplData). So, for a three-column ListView with a one-column ApplData property otherData, invoking SortByColumn 4 uses the sort order of otherData[;1] to re-order the ListView. This allows dates, for example, to be formatted in any way and displayed in the third column of the ListView. Provided the serial values of the same dates are stored in the corresponding rows in otherData[;1], it is possible to sort the ListView chronologically by associating the expression CC: ⍺ ∇Do 'SortByColumn' ((1 2 4)[⊃⍵]) with the ColumnClicked event (320) in the Event/action table for the ListView control. The expression directs SortByColumn to derive the sort order from the values in column four (otherData[;1]) whenever the header of column three is clicked.

Passing a column value of ¯1 to SortByColumn has the effect of using the the same column and direction (ascending or descending) as the most recent sort. This is allows you to maintain the sort order after changing a value in, or adding a row to, the ListView contents.


CPro Turorial and Reference: Numeric Matrix (MA)

Numeric Matrix (MA)

Description

Provides a scrolling matrix edit facility for a simple numeric array. The user cannot change the shape of the data.

For more details on the Specification property, see the Text Matrix class.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Values | User |  | Numeric Values matrix
Specification | Runtime |  | Grid Specification
Column Titles | Runtime |  | Text vector of column headers
Row Labels | Runtime |  | Text vector to label rows
CurrCell | User |  | Location of cell (two-element int vec)
Index | User |  | Location of top corner (two-element integer vec)

Class-specific Events

PC | Post Create
HR | Help Request

Class-specific Functions

Move | Shift current cell
Info | Returns (offset)(index)


CPro Turorial and Reference: Numeric Matrix - Move Function

Numeric Matrix – Move Function

Forces the input cell to the given [row;col]

ma ∇Do 'Move' 3 4

These values are in the ⎕IO of your application. Use ¯1 in row/col to leave the location as is on that axis.


CPro Turorial and Reference: Numeric Matrix - Info Function

Numeric Matrix – Info Function

Can be used to query the current cell and scroll position of the grid. Most likely use is on a button which should run a function on a particular cell:

SL : Drill 2⊃ma ∇Do 'Index'


CPro Turorial and Reference: MDI Child Form (MDI)

MDI Child Form (MDI)

Description

MDI Child sub-form. The Menu property is used to name the menu on the parent form which is to be used to manage the MDI stack. This must match the name in the parent’s menu structure exactly ...

  &File>file
  &Window>window
 [window]
  &Cascade ... etc

In this example, use the name ‘window’ to attach the MDI children.

Designed as if it were a stand-alone form. You can call it (to see the effect) from the session, but normally you would use ∇Make to make all the MDI children as a create action on the parent form.

Class Property Table

Name | Type | Default | Description
Locals | NameList |  | Local variables
Titlebar | Runtime |  | Form caption
Menu | Runtime |  | Parent’s Window Menu (e.g. ‘window’)

Class-specific Events

CL | Close Request
PC | Post Create
WA | Wake-up Call

Class-specific Functions

SetIcon Set System/Minimised Icon from file or APL array


CPro Turorial and Reference: MDI Child Form - CL Event

MDI Child Form – CL Event

The Close Request may be used to save data, or allow the user to continue, if you reject the event having offered a suitable dialogue.


CPro Turorial and Reference: Most Recently Used (MRU)

Most Recently Used (MRU)

Description

Manages the Most Recently Used files list on your File Menu.

When refreshed with a file name, it checks this against the current list, and updates as required. If the file is already there, it gets pulled to the top. Otherwise it is added, and if the limit on number of files has been reached, it drops the last one.

It will also maintain an entry called:

 [Recent File List]
 File1=blaaah

... in your .INI file or with a given Registry key, if you give a file name or path as the second element in the reference. The default limit is to remember 4 files.

N.B. the <File Menu Name> in the reference data is the name in square brackets (such as [file]) in your menu definition. This is case-sensitive, so be careful!

Names longer that the allowed maximum are shortened from the middle outwards e.g. S:\server\...\...\myfile.qwe to limit menu width.

Class Property Table

Name | Type | Default | Description
File name | Runtime |  | Current File Name
Specification | Runtime |  | (File Menu name)(INI file or Registry path)(No. of files {4})
Max length | Int | 36 | Maximum name-length before shortening
Storage | OneOf |  | Where to store the list

Class-specific Events

FO File Open Request (MRU)

Class-specific Functions

SetSection Change the default name for the INI section or Registry key


CPro Turorial and Reference: Most Recently Used - FO Event

Most Recently Used – FO Event

Reported on the MRU manager when the user selects one of the entries from the [file] menu in the application. It reports the file name as the event argument (enclosed, as there could be more than one file), so a typical action could be:

FO : ∆file←OpenFile ⊃⍵ : ∆file :

Note that the MRU will be watching ∆file, and will update the list automatically when this is hollered.


CPro Turorial and Reference: Numeric Field (NM)

Numeric Field (NM)

Description

Edit field which watches a numeric singleton.

Format should be an expression that gives a format specification such as 8 2 or a valid argument to Quad-FMT. The field will reject keystrokes which are not valid in a number, or if you exceed the length or decimal places allowed by the format (only if supplied as a numeric argument).

Note that a format of 8 is read as {8 0}, which is not quite the same as the format primitive. If no format is given, the APL default format is used.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Number | User |  | Number (single number)
Format | Runtime |  | Format (8 2 for thorn or ‘CF7.2’ for #FMT)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help Request


CPro Turorial and Reference: New-Open-Save-Exit (NOSE)

New-Open-Save-Exit (NOSE)

Description

Offers Windows-standard behaviour on File-Open etc. To use this object, you will need to set the current file name as data, the filebox prompt as specification, and then field a number of events in the Behaviour table.

The actions will be called automatically, depending on the results from previous actions, and the state of the system, for example whether a file of the same name is already on disk. The NOSE events you should handle are:

   ASK - ⍵← is the data dirty
  GET - YourReadFunction ⍵
  PUT - YourWrite Function ⍵
  ZAP - YourClearFunction

ASK is optional – if you do not record the fact that the user has modified some data since the last ‘GET’, a good safety feature would be to include ⍵←1 here so that the application always prompts ‘Do you want to save?’ on exit.

Typically you will invoke the NOSE from your File menu, for example:

&Open: nose ∇Do 'Open'

A good place for the ‘Exit’ call is on the Close Request on your main form as it returns zero if the user cancels ...

CR: 0=nose ∇Do 'Exit : ∇Reject : :

Class Property Table

Name | Type | Default | Description
File name | User |  | Current File Name
Specification | Runtime |  | File Prompt (‘*.ext’ ‘Application name’ )

Class-specific Events

ASK | Am I dirty?
PUT | Save this File!
GET | Open this File!
ZAP | Clear this Workspace!

Class-specific Functions

Exit | Handles all that needs to happen on File/Exit
Save | Handles all that needs to happen on File/Save
SaveAs | Handles all that needs to happen on File/SaveAs
New | Handles all that needs to happen on File/New
Open | Handles all that needs to happen on File/Open
SetNewName | Sets name for next new file
FileExists | Check if file is already there
SetDirectory | Set search directory for File,Open
SetSaveMsg | Replace the default ‘save file?’ prompt
SetReplMsg | Replace the default ‘overwrite?’ warning


CPro Turorial and Reference: New-Open-Save-Exit - ASK Event

New-Open-Save-Exit – ASK Event

This is queued by the NOSE to allow the application to decide if there is any unsaved data which may be lost on opening a new file.


CPro Turorial and Reference: New-Open-Save-Exit - SetSaveMsg Function

New-Open-Save-Exit – SetSaveMsg Function

May be called to replace the default ‘save file?’ prompt with your own message

⍺ ∇Do 'SetSaveMsg' 'Would you like your data saved?'


CPro Turorial and Reference: New-Open-Save-Exit - SetReplMsg Function

New-Open-Save-Exit – SetReplMsg Function

Used to replace the standard warning message when a file is about to be overwritten:

⍺ ∇Do 'SetReplMsg' 'Watch it!'


CPro Turorial and Reference: Notepad (NP)

Notepad (NP)

Description

Basically a multiline edit. Text should be a nested text vector. If WantsEnter is set (the default) keystrokes are monitored for ‘Enter’ which is used to get a new line, not to hit the <OK> button. ‘Ctrl+Enter’ does this instead.

Will accept commands Enable, and Disable which disables typing, but allows cursor keys and clipboard copy. The text is set to dark grey when disabled.

The selection is constantly updated to reflect the cursor position, or may be set by the application to select a specific region.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
WantsEnter | Bool | 1 | Captures <Enter> key
Style | ManyOf |  |
Text | User |  | Text (vector of text vectors)
Selection | User |  | Selected text (2-vector of from-to) pairs
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help request


CPro Turorial and Reference: Numeric Vector (NV)

Numeric Vector (NV)

Description

Single-line numeric edit for a blank-separated vector.

Tolerates all reasonable separators, but always echoes back with blanks. Will accept any valid APL numbers.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Values | User |  | Numeric vector
Format | Runtime |  | Format (8 2 for thorn or ‘CF7.2’ for #FMT)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help Request


CPro Turorial and Reference: Parameter Bar (PA)

Parameter Bar (PA)

Description

Uses a scroll-bar and some labels to make a slider bar to set the value of a numeric variable.

Caption – is written centrally above the bar

Value – should be a numeric scalar

Limits – sets the min, max, and step values.

The bar can be dragged between min/max. If this is a text vector (e.g. ‘Hi’ ‘Lo’) the bar is ranged from [1..100] and the range is shown at the ends.

Step defaults to 1 if omitted.

Class Property Table

Name | Type | Default | Description
Value | User |  | Value variable (number)
Limits | Runtime |  | Limits variable (min,max,[step])...


CPro Turorial and Reference: Picture Button (PB)

Picture Button (PB)

Description

A pretty version of the Action Button. These are for slightly fancy toolbars, optionally in the Office97 ‘lightup on mouse’ style.

The Bitmap field sets the picture. This is shown centred in the top third of the button, above the caption. It is best to keep these bitmaps small (e.g. 32 by 48). They can also look good with built-in 3D effect. If there is no caption, the bitmap is vertically centred.

The Style sets the button behaviour (default ‘Push’). A good use of this is for ‘PowerPoint’ tool buttons, which need ‘Radio’ behaviour.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
ToolTip | String |  | Tip (simple text vector)
Bitmap | Runtime |  | Bitmap ‘file name’ or bits array
Drawn | OneOf |  | Visual style (e.g. Office97)
Style | OneOf |  | Push, Radio or Check
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Progress Indicator (PI)

Progress Indicator (PI)

Description

A long, thin rectangle used to show % complete when reading big files, or running long calculations. Will accept a data variable (the current and target values) with the default target taken as 100. However a more common use is to update it from within a processing loop:

:For ct :in ⍳todo
...
pb #.CPro.Do 'Set' (ct todo)
...
:EndFor

... which updates immediately. You could also set the Value variable here and use 1 #.CPro.Notify to get the same effect.

N.B. If you need Abort functionality, you should use the GuiPbar namespace instead:

#.GuiPbar.Open 'Please Wait'
#.GuiPbar.Set (ct todo)
→(1=#.GuiPbar.State)↑Abort
#.GuiPbar.Close

This provides a standard ‘ontop’ progress tracker which you can use to check if the user hit the <Cancel> button.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Value | Runtime |  | Progress to date (current,max)
Drawn | OneOf |  | Visual style (Continuous or blocky)
Format | Text | ‘? of #’ | Message text (? done of total #, ~ to do)

Class-specific Functions

Set | Explicit setting of amount completed
SetText | Set new text to embed values in


CPro Turorial and Reference: Progress Indicator - Format Property

Progress Indicator – Format Property

Allows you to change the standard message format. The default is "? of #" where the two placeholders are replaced with the amount done and the total amount to be done. You can also use ~ to stand for “to do”.

A typical setting might be “Records processed ?, from # in total”.


CPro Turorial and Reference: Plinth or Recess (PL)

Plinth or Recess (PL)

Description

Decorator used to emphasise objects. Default is a depth of -1 (i.e. a 1-pixel plinth).

The Depth property can be used to set depths (1-3 are OK, >3 and the 3D effect fails).

This is drawn entirely within its rectangle, so you can ‘plinth’ an entire dialog box using (0 0)(fm-size). This works well on application banners with a depth of -3.

Class Property Table

Name | Type | Default | Description
Depth | Runtime |  | Depth (negatives give plinths)


CPro Turorial and Reference: Poly Marker (PM)

Poly Marker (PM)

Description

Poly Marker from a matrix of co-ords and optional captions. If present, the caption is written below the object in reverse colour.

Points is (n × 2) matrix of centres or (n × 3) matrix with an additional column of captions

Icon is the Icon File to use (one icon is used for all the points) or a 3D array of which the first plane defines the colours and the second plane is a boolean mask defining the transparency.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Points | Runtime |  | Points matrix (r c [caption])
Icon | Runtime |  | Icon ‘file’ or Icon Definition matrix (2;32;32)


CPro Turorial and Reference: PostScript Graphics (PS)

PostScript Graphics (PS)

Description

Interfaces to the “RainPro” Graphics Interpreter. Use this to display a ‘pre-cooked’ chart which has been stored in the workspace as a character vector of PostScript code.

Will keep the aspect ratio of the original chart, so the shape of the field should roughly match the shape of the graph. An aspect of 3 high by 4 wide is normal.

Right-mouse on the chart offers options such as zoom to full-screen, and printing; left-mouse drags a locator which queues a DSL (Drag-select) event on the object when released. This gives a 2×2 table (x1y1 x2y2) of the lower-left and upper-right corners in the co-ordinate system of the chart.

It also queues a ZM (Zoom) event which can be used as the argument to Rescale to zoom the view in place. The arrow keys can then be used to walk around the view.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Tooltip | String |  |
Page No | Runtime |  | Page number (integer)
PostScript | Runtime |  | Graphic to draw (PostScript vector)
Dragable | StringList |  | Names of editable data series
Tracking | Bool | 1 | Fire events as data is dragged
PSPath | txt | ‘#.PostScrp’ | Path to PostScript namespace
LeafPath | txt | ‘#.leaf’ | Path to NewLeaf namespace (optional)

Class-specific Events

DSL | Drag Selection
ZM | Zoom
RS | Chart resized
RMM | Right-mouse menu
COBJ | Chart Object clicked
CDATA | Chart Data clicked
CHINT | Data hint
CDXY | XY co-ordinates
CDSTART | Chart drag start
CDTRACK | Chart drag in progress
CDEND | Chart drag ended
CDOVER | Mouse over dragable series

Class-specific Functions

Where | returns current (posn)(size) in pixels
Rescale | redraws the chart so the selected region (x1 y1 x2 y2) is drawn full-screen
Clipboard | Copy chart to clipboard
Print | Print chart to default Printer
SetSeries | Update list of editable series
WriteEPS | Save chart as Encapsulated PostScript file


CPro Turorial and Reference: PostScript Graphics - DSL Event

PostScript Graphics – DSL Event

This event is raised when the user drags a rectangle over a chart. It reports a 2-by-2 matrix with the (x1,y1)(x2,y2) co-ordinates of the upper left and lower right corners of the surrounded area (regardless of the direction of drag) in the co-ordinate system defined by the chart axes.

This may be used by the application to identify data points which have been enclosed by the user.


CPro Turorial and Reference: PostScript Graphics - ZM Event

PostScript Graphics – ZM Event

Reported when the user drags a ‘rubber band’ rectangle over a chart shown by the PostScript viewer. May be used by the application to zoom in on the selected region:

ZM : ⍺ ∇Do 'Rescale' ⍵

This will use the top edge of the dragged area as the base from which to draw a new chart as large as possible, but maintaining the correct aspect ratio.


CPro Turorial and Reference: PostScript Graphics - RS Event

PostScript Graphics – RS Event

This is signalled to the PostScript object when it is resized by the user – the message gives the new size. A likely response is to force a refresh of the chart to get it rescaled to fit in the new space available.


CPro Turorial and Reference: PostScript Graphics - COBJ Event

PostScript Graphics – COBJ Event

This event is reported when you release the mouse over a chart object such as a heading or caption. See the Chart Class for details.


CPro Turorial and Reference: PostScript Graphics - CDATA Event

PostScript Graphics – CDATA Event

This event is reported when you release the mouse over a data point such as a marker, a bar or a pie wedge. The event message is reported as a 4-element vector – see the Chart Class for details.


CPro Turorial and Reference: PostScript Graphics - CHINT Event

PostScript Graphics – CHINT Event

This event is reported when the mouse is moved over any data point which has been given a ‘Hint‘ property using ch.Hint as the chart was constructed.


CPro Turorial and Reference: PostScript Graphics - CDXY Event

PostScript Graphics – CDXY Event

This event reports the current position of the mouse in chart(x,y) co-ordinates as a text vector (null if it is not over a region bounded by chart axes).


CPro Turorial and Reference: PostScript Graphics - CDSTART Event

PostScript Graphics – CDSTART Event

This event is reported when a user begins to move a dragable datapoint. The message reports the (chart, series, row, column) as a 4-element vector. You may drag markers or bars which are listed in the ‘dragable’ property of the class. Please note that if you drag a bar from a stacked barchart, you will be given the new y-value as the sum of this bar and the bars beneath – it is up to you do subtract the appropriate offset to the base of the bar. You may reject the event by returning 0 from the event-action table (⍵←0 or ∇Reject) – this could be used to allow selective update from a set of grouped bars.


CPro Turorial and Reference: PostScript Graphics - CDTRACK Event

PostScript Graphics – CDTRACK Event

This event is reported as you drag a data point from a dragable series. The message reports the (chart, series, row, column, new-x, new-y) as a 6-element vector. To get this stream of events, set the ‘Tracking’ property to ‘true’, otherwise you only get the CDSTART and CDEND events on mouse-down and mouse-up. You may reject the event, or modify the message by changing elements of ⍵, for example to provide a ‘stepping’ behaviour by rounding to some appropriate batch size.


CPro Turorial and Reference: PostScript Graphics - CDEND Event

PostScript Graphics – CDEND Event

This is reported when a dragable data-point is released. The message format is the same as for the CDTRACK event, i.e. (chart, series, row, column, new-x, new-y) as a 6-element vector.


CPro Turorial and Reference: PostScript Graphics - WriteEPS Function

PostScript Graphics – WriteEPS Function

This takes a file name and generates a standard ‘Encapsulated PostScript’ file for inclusion in any DTP software such as MS Publisher or MS Word. See the Chart Class for details.


CPro Turorial and Reference: Polyline (PY)

Polyline (PY)

Description

Polyline from a matrix of co-ords. The simple case is a two-column matrix, but any valid Dyalog PolyLine definition is OK.

Properties gives the Colour (0 – 15); weight (default 1 pixel); style (default solid); Fill Colour. You can give as many elements as required here.

Note that this applies to the entire poly or set of polys.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Points | Runtime |  | Polyline matrix (r c)
Properties | Runtime |  | Colour (0-15) [,Weight,Style,FillColour]


CPro Turorial and Reference: Cancel Button (QT)

Cancel Button (QT)

Description

A simple button, but with the Dyalog (‘Cancel’ 1) property preset. It closes the parent form when the user hits <Esc>.

The form will return 0 from #.CPro.Call when closed with a <Cancel>. Any “Select” action you put on this button will run, but will inhibit the default action. Add #.CPro.Return 0 to reinstate the default behaviour.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |


CPro Turorial and Reference: Radio Button Group (RB)

Radio Button Group (RB)

Description

This makes a group of radio buttons captioned at the group level (may contain &Accelerators). You can have this watch/update an index value (singleton) or a boolean vector of button states, which will only ever have one bit set.

Labels – is a matrix of button captions where the shape sets the layout of the group. A vector is treated as a one-column matrix, giving a vertical arrangement.

The buttons are spaced out evenly within the object size. The keyboard arrows can be used to switch between them.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Index | User |  | Index variable (selected index)
States | User |  | Boolean vector (button states)
Labels | Runtime |  | Labels List (button labels)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Containing Region (RGN)

Containing Region (RGN)

Description

Makes another dialogue definition within itself. Has no visible presence unless you set a suitable 3D effect.

The child definition(s) should be designed as a Subform or Tabbed Subform to allow it to be placed within the container on creation.

It is launched in the corresponding namespace (if given). If a vector of namespaces is given for a single form, multiple forms will be launched (suitable for TSF form class only). Note that you can have a single form dynamically change namespace by placing it within a region.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
CurrentNS | Runtime |  | Namespace where data is found and actions run
3D | OneOf |  | Border style
Backdrop | Metafile |  | Region backdrop (will stretch to fit)
Colour | Colour |  | Background colour of region (r,g,b)
Subforms | Runtime |  | Subform Definition(s)
Topform | User |  | Index of front form (tabbed forms only)
Namespaces | Runtime |  | Where to make the subforms
Scrollable | Bool |  | Add scrollbars if needed
MDI capable |  | Bool ⍝ Supports full MDI capability |
Page Size | Runtime |  | Logical size of page (rows,cols)
Offset | User |  | Location of top corner (row,col)

Class-specific Events

PC Post-create

Class-specific Functions

Where | Returns position and size in Pixels
Children | Lists current child forms
SetColour | Sets the background colour (r,g,b)
SetBackdrop | Sets a metafile as the region backdrop


CPro Turorial and Reference: RTF Editor (RTF)

RTF Editor (RTF)

Description

View or edit a WordPad-compatible rich text file or APL variable. Note that this is not a particularly complete RTF viewer – use Word if you really want to see what a file looks like.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Filename | Runtime |  | Filename (e.g. ‘mydoc.rtf’)
Richtext | User |  | Editable content
Editable | Bool |  | Do we enable editing tools
ReadOnly | Runtime |  | Change readonly-status on the fly
Enabled | String | ‘BIULCR’ | Enabled tools (default is all)
Units | OneOf | ‘Pts’ | Units for indents and tabstops
Hotkeys | String | ‘BIULER’ | Accelerator keys for all tools (including disabled)
Tips | String | ∆tips | Text for button tips for all tools (,sep list)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

RBM | Right-mouse Menu
KP | Keypress
FC | FirstChange (by any means)

Class-specific Functions

FileRead | To load/regenerate contents, and
FileWrite | To save the edited contents to file.
SetIndents | Set Left, Firstline, Right indents in current units
SetTabs | Set up tabstops in current units
SetText | Set content from a plain text variable
ReadText | Query the current content with no formatting codes
SetImage | Assign a non-default bitmap strip to the tool buttons


CPro Turorial and Reference: Floating Palette (RU)

Floating Palette (RU)

Description

Makes a floating tool palette. Useful in conjunction with MDI children, where the CurrentNS can be set to track the namespace of the child forms.

Class Property Table

Name | Type | Default | Description
Locals | NameList |  | Local variables
CurrentNS | Runtime |  | Namespace where data is found and actions run

Class-specific Events

PC | Post-Create
WA | Wake-up Call
CL | Close Request


CPro Turorial and Reference: Status Area (Parent Region) (SA)

Status Area (Parent Region) (SA)

Description

Provides a home for Status Fields and Progress Indicators. Can be used to design custom Status Bars when the simple Status Bar class is not sufficient.

Design this as a stand-alone form using 'SA' Dbx 'dbx.sa' then make it on creation of the main form with ∇Make dbx.sa. The only valid children are PI (progress indicator) and SF (status field).


CPro Turorial and Reference: Scroll Bar (SB)

Scroll Bar (SB)

Description

A simple scroll bar. Will change orientation automatically when resized, and snap to 16 pixels on the smaller dimension.

Thumb – should be a numeric integer between 1 and max

Range – sets the max, [step] values.

The bar can be dragged between [1..max] (default 100). Step defaults to 1,10 if omitted.

Class Property Table

Name | Type | Default | Description
Thumb | User |  | Thumb (integer 1..max)
Range | Runtime |  | Range, small step, large step


CPro Turorial and Reference: Status Field (SF)

Status Field (SF)

Description

Should only be used as the child of a Status Area. Allows you to design a complex status bar with several fields. The Caption is used as permanent text and is spaced from the Text so that you might have a caption ‘Bytes copied’ and an integer counter for the text.

N.B. Only one of these fields should take the hints from the main form!

Class Property Table

Name | Type | Default | Description
Caption | Runtime |  | Label value (persistent)
Text | Runtime |  | Transient text
Style | ManyOf |  |
WantsHint | Bool |  | Takes Hints from objects on the main form
WatchKey | OneOf |  | Key to monitor (e.g. Caps)

Class-specific Functions

Set Set temporary/permanent text in the field


CPro Turorial and Reference: Drop-down Selection (SL)

Drop-down Selection (SL)

Description

Very like the List Box, but you don’t see it until it is dropped down. Single-item selection only. Unfortunately double-click can’t be done here.

Expects and updates an Index (numeric singleton, returned as a scalar).

The Items data is a nested text vector, or a simple text matrix.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Index | User |  | Index variable (Index)
Items | Runtime |  | Items List (drop-down contents)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Spin Box (SP)

Spin Box (SP)

Description

A numeric-entry field, with a pair of spin buttons to wind the contents up and down.

The reference field gives an increment for the contents, or is a vector of numbers or text with the valid values for the contents.

The buttons will spin the field through these values, but the user can jump by typing into the edit part if necessary. By default CPro will refresh other controls as the value spins – to have the new value notified only on release of the mouse, set Tracking=0.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Value | User |  | Value (simple number, or index into list)
Step | Runtime |  | Increment or Step List
Delay | Int | 400 | Initial delay (ms)
Interval | Int | 50 | Repeat interval (ms)
Tracking | Bool | 1 | Update data every click
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Status Bar (ST)

Status Bar (ST)

Description

A simple Status Bar which sticks to the bottom of the screen.

It includes a field to take ‘Hint‘ information from other objects and a right-aligned field to monitor the state of the ‘CAPS’ key.

Supports the ‘Set’ command to update its caption, for example to inform the user of progress during a long operation.

Will automatically adjust the positions or sizes of any objects in its “Controls” list when it is hidden or shown.

Class Property Table

Name | Type | Default | Description
Caps | Bool | 1 | Show CapsLock indicator
Num | Bool | 0 | Show NumLock indicator
Scrl | Bool | 0 | Show ScrollLock indicator
Controls | Stringlist |  | Objects to adjust (group ids)
Visible | User |  | Show or hide the ststus bar (boolean scalar)

Class-specific Functions

Set Temporary or permanent setting of status text


CPro Turorial and Reference: Status Bar - Controls Property

Status Bar – Controls Property

When the status bar is shown or hidden, it is likely that several other controls will need to be resized or moved to use the remaining space correctly. To have this happen automatically, put any affected controls into a suitable group (such as ‘SBAR’) and set this group name as the “Controls” property. You can list several groups here if necessary.


CPro Turorial and Reference: Subform (SUB)

Subform (SUB)

Description

Designed to be set as the Subform data of a containing region (RGN). This allows forms to be toggled over part of another form, or tabbed subforms to occupy only a section of the main form.

If the parent region is set to be ‘scrollable’, make sure to set Scaled=False here. The size may be determined at runtime if it is not known when the form is designed.

Class Property Table

Name | Type | Default | Description
Locals | Namelist |  |
Scaled | bool | 1 | Scaled to fit parent region
Colour | colour |  | Background colour (r,g,b)
Visible | Runtime |  | Boolean singleton


CPro Turorial and Reference: Systray Item (SYS)

Systray Item (SYS)

Description

Inserts an icon in the System Tray on the toolbar. You should always specify a 16 by 16 icon definition here.

Would normally be used to put up a menu (on the RBM event) or open a dialogue-box (typically on double-click). Currently you cannot cancel the menu except by clicking an item, so be sure to include a dummy ‘Cancel’ entry here.

Class Property Table

Name | Type | Default | Description
ToolTip | Text |  | Tip to show over the system tray
Icon | Runtime |  | Icon ‘File name’ or bits array

Class-specific Events

LMC | Left-button clicked
RBM | Right-button menu


CPro Turorial and Reference: File Tabs (TAB)

File Tabs (TAB)

Description

This makes a set of file tabs (right aligned by default). May be used to fake a tabbed dialogue box when the content is repeated throughout the pages (such as a 3-dimensional matrix).

Caption – ignored

Index – should be an integer singleton.

Tab labels – is a text vector of tab labels.

Alignment – sets the edge of the associated control to align to.

The tabs are spaced out evenly within the object size, and will use a mini-scrollbar if there is insufficient room. Use the smalltext style to save space on top and bottom tabs.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Index | User |  | Index variable (selected index)
Tab labels | Runtime |  | Tab labels List (tab labels)
Alignment | Oneof | ‘Right’ | Direction of tabs (left, right, top, bottom)


CPro Turorial and Reference: Toolbar (TB)

Toolbar (TB)

Description

Toolbar (top or left aligned depending on shape)

Class Property Table

Name | Type | Default | Description
Locals | Namelist |  |
Style | ManyOf |  |
CurrentNS | Runtime |  | Namespace where data is found and actions run


CPro Turorial and Reference: Tool Control (TCTL)

Tool Control (TCTL)

Description

Interface to the IE4-style ‘Rebar’ controls. You can have a single toolbar, or you can set the ‘Cool’ property to “true” to allow several toolbars to share the same region at the top of the form. At present, the only valid child control is the new-style tool button.

As the user drags these around, the depth of the parent region may change (also setting captions on/off will affect this) so you can ask the toolcontrol to manage a collection of other objects by listing any number of group names in the Reposition property.

N.B. If you have several toolcontrols, only set this property on the first one you create. You can use the ‘Sequence’ property to change the actual order in which they appear.

N.B. Do not set the ‘Newline’ property of the first control in the sequence to 1, Dyalog tolerates this, but it confuses the repositioning algorithm!

Class Property Table

Name | Type | Default | Description
Locals | Namelist |  |
Align | OneOf | ‘Top’ |
Style | OneOf |  |
Cool | Bool |  | Occupy a ‘Coolbar’ parent
Newline | User |  | Does it start a new line in the coolbar?
Sequence | Runtime |  | Order relative to other tool controls
Artwork | Runtime |  | e.g. a 16 × 16n integer array of bitmap data
SeeThru | Int | 8 | Colour used as transparent (not yet implemented)
Captions | Runtime |  | Boolean – are captions shown on the buttons
Visible | Runtime |  | Is ToolControl visible (boolean)
Reposition | Stringlist |  | Group(s) to be repositioned when size changes or bar is hidden
CurrentNS | Runtime |  | Namespace where data is found and actions run

Class-specific Events

PC | Post-Create
CAP | Captions on/off

Class-specific Functions

GetIndex Query sequence relative to other controls


CPro Turorial and Reference: Tool Control - Newline Property

Tool Control – Newline Property

This is a boolean-valued variable which determines if the toolbar starts a new line in the parent region. If the user drags the toolbar handle downwards, the toolbar will follow along, and Causeway will update the variable for you. You might like to save this on an INI file (or in the registry) so that the toolbar configuration is restored when the application is reloaded.


CPro Turorial and Reference: Tool Control - Sequence Property

Tool Control – Sequence Property

This is an integer-valued variable which you can set to determine the order of the toolbars in the parent region. Unfortunately no event is signalled when the user drags a toolbar left or right, so to save the user’s preferences on exit you must run the GetIndex function to query the settings for each toolbar in turn.


CPro Turorial and Reference: Tool Control - Artwork Property

Tool Control – Artwork Property

This specifies a bit-strip to use as the sequence of images for all the tool buttons. The standard Win95 tools are all 16x16 pictures, but you may find 19x19 more comfortable. You should supply a single integer array, for example to provide the pictures for 12 tools you will need a 16 x 192 array of colour values. You can make this in Windows Paint in the usual way (be sure to save as 16 colour), then read the bits property into the workspace, or you can use the supplied Picstrip namespace as your editor.


CPro Turorial and Reference: Tool Control - Reposition Property

Tool Control – Reposition Property

The major application challenge in using the new toolcontrols is in moving any related controls around when the user shows or hides a toolbar, drags it to a new line, or turns the captions on or off. Taken in combination, these changes can greatly affect the remaining area of the form, and many other controls may need to be resized or moved.

To have this happen automatically, put any affected controls into a suitable group (such as ‘TBAR’) and set this group name as the “Reposition” property. You can list several groups here if necessary.


CPro Turorial and Reference: Tool Control - CAP Event

Tool Control – CAP Event

Queued by the class whenever captions are turned on or off. The event argument gives the new toolbar height – other controls will probably need to be moved to accommodate it.


CPro Turorial and Reference: Timer (TI)

Timer (TI)

Description

Adds a timer to your form. Use the TI (timer) event to trigger actions.

TI : time+←1 ⋄ 'tick' : time

Be careful with timers which echo to the session (as above) – it can be very hard to kill these as you never get the opportunity to type anything useful! Maybe you should set #.CPro.Reset on a function key before experimenting.

A handy use for a timer is to close an application banner after (say) 4 seconds: just set a timer at 4000 and add an action for:

TI: :∇Return 0: :

which will close the form automatically.

Class Property Table

Name | Type | Default | Description
Interval | Runtime |  | Interval (time in ms)

Class-specific Events

TI Timer


CPro Turorial and Reference: Track Bar (TKB)

Track Bar (TKB)

Description

A Windows95 track bar. Will change orientation automatically when resized, and can be styled to have a recessed centre.

Thumb – should be a numeric integer within the given limits

Limits – sets the min, max, [steps] values.

The bar can be dragged between [min..max] (default [1..100]).

Step defaults to (1,10) if omitted. Set Tracking=0 to prevent other CPro controls refreshing while the thumb is being dragged.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Thumb | User |  | Thumb (integer)
Limits | Runtime |  | Limits, [step], [large step]
Tracking | Bool | 1 | Signal changes during drag


CPro Turorial and Reference: Tool Button (TL)

Tool Button (TL)

Description

Toolbar push-button (old style). Select should trigger its action. The ToolTip gives the bubble-help to show over the button (split at ‘;’ into multiple lines). The caption is taken as a bitmap name, but may be overridden at runtime by the Bitmap value.

Note that the captions:

*New *Open *Save *Print *Copy *Paste

are internal to the APL interpreter, and can be accessed directly with these keywords.

Use small bitmaps to make toolbar-style controls; 16 by 15 is a good size to put on a 20×20 button.

Standard functions Enable and Disable will grey out the bitmaps as necessary.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Accelerator | String |  | Hotkey (e.g. Ctrl+S)
ToolTip | Runtime |  | Tip (simple text vector)
Bitmap | Runtime |  | New Bitmap (bits or file name)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


CPro Turorial and Reference: Text Matrix (Grid) (TM)

Text Matrix (Grid) (TM)

Description

Provides a scrolling matrix edit for cellular text data. Rows may be added, deleted and moved using right-mouse menus on the row titles.

Use the standard ‘Grid‘ property specifications to set the detailed look of your data, for example set the ‘reference’ to:

Coltitles=Id,Name,Dept
CellWidths=72 300 144
Titlewidth=48

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Style | ManyOf |  |
Values | User |  | Text matrix
CurrCell | User |  | Location of cell (two-element int vec)
Specification | Runtime |  | Grid Specification
Column Titles | Runtime |  | Text vector of column headers
Row Labels | Runtime |  | Text Vector to label rows
Row Ops | ManyOf | ‘ICDM+’ | Row Menu options
Col Ops | ManyOf | ‘FS’ | Column menu options
Cnr Ops | ManyOf | ‘UGR’ | Corner menu options

Class-specific Events

PC | Post Create
HR | Help Request
GDC | Grid DoubleClick

Class-specific Functions

Move | Shift current cell
Info | Return (offset)(index)
RowOps | Set new row operations
WideCols | Nominate Soakaway columns
SetBcol | Set Cell Background
SetFcol | Cell Foreground
Append | Append row
SetAction | Set Select handler function on buttons
SetItems | Update dropdown list in-place
GetItems | Query current dropdown list


CPro Turorial and Reference: Text Matrix (Grid) - Row Ops Property

Text Matrix (Grid) – Row Ops Property

Controls the right-mouse menu offered by the grid control on the row labels. Include the initial letters corresponding to the options you want from:

Append,Insert,Copy,Delete,Move,+Pad+

The ‘+’ causes the addition of empty cells at the end of the table, which are removed automatically if not used.


CPro Turorial and Reference: Text Matrix (Grid) - Col Ops Property

Text Matrix (Grid) – Col Ops Property

Controls the right-mouse menu offered by the grid control on the column headers. Include the initial letters corresponding to the options you want from:

Find,Sort


CPro Turorial and Reference: Text Matrix (Grid) - Cnr Ops Property

Text Matrix (Grid) – Cnr Ops Property

Controls the right-mouse menu offered by the grid control on the top-left corner. Include the initial letters corresponding to the options you want from:

Undo, Go To Cell, Renumber


CPro Turorial and Reference: Text Matrix (Grid) - GDC Event

Text Matrix (Grid) – GDC Event

A grid cell was double-clicked (text or numeric matrix). This might be used to generate more detailed information on the chosen cell. For the cell co-ordinates see 2↑4↓⍵.

Note that you will get this event if the user double-clicks on the grid headers – the row/column index will be ¯1 in this case (¯1 ¯1 is the top corner). These co-ordinates are always reported in ⎕IO=1.


CPro Turorial and Reference: Text Matrix (Grid) - WideCols Function

Text Matrix (Grid) – WideCols Function

By default, the TM class allocates spare width evenly across all cells. To give all the space to the second column (possibly a description) ...

CR : ⍺ ∇Do 'WideCols' 2

You can list several column indices here to get the space distributed as required. If you include a column several times in the list, it is given space in proportion to the number of appearances.


CPro Turorial and Reference: Text Matrix (Grid) - SetBcol Function

Text Matrix (Grid) – SetBcol Function

Sets a collection of cells to a given background colour:

⍺ ∇Do 'SetBcol' (255 255 0)(1 1)(2 3)(5 6)

Argument is a vector of numeric vectors. The first element gives the background colour, remaining elements give the scatter-indices of the target cells.


CPro Turorial and Reference: Text Matrix (Grid) - SetFcol Function

Text Matrix (Grid) – SetFcol Function

Sets a collection of cells to a given foreground colour. Could be used to flag data out of range after update by the user:

PU : ⍺ ∇Do 'SetFcol' (128 0 0),(,data>20)/,⍳⍴data

Argument is a vector of numeric vectors. The first element gives the text colour, remaining elements give the scatter-indices of the target cells.


CPro Turorial and Reference: Text Matrix (Grid) - SetItems Function

Text Matrix (Grid) – SetItems Function

Updates the lookup items of a grid dropdown given the column number and a new item vector. Returns the previous value.

 ⍺ ∇Do 'SetItems' 2 ('Fat' 'Cat')  ⍝ NB ⎕IO here


CPro Turorial and Reference: Tool Button - new style (TO)

Tool Button – new style (TO)

Description

Toolbar button for use with the new Toolcontrol. You have no control over the layout of the buttons – they are simply created in sequence, so use the object sorter to put them into the correct order. The ToolTip gives the bubble-help to show over the button. The caption will be shown depending on the ‘ShowCaption’ property of the parent tool control. Note that the pictures on the buttons are defined by the artwork property of the parent toolcontrol, and if captions are off, the picture size determines the size of the button. You can override the picture index if you wish – by default the tools pick up the images in the order of creation.

To add separators (a vertical groove in a standard toolbar) use a toolbutton with the ‘separator’ style and no caption.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Accelerator | String |  | Hotkey (e.g. Ctrl+S)
ToolTip | String |  | Tip (simple text vector)
ImageIndex | Int |  | Overrides default image sequence (Origin-1 always)
Active | Runtime |  | Boolean singleton
Style | OneOf |  |
Menu | Runtime |  | For buttons with style ‘dropdown’


CPro Turorial and Reference: TreeView (TR)

TreeView (TR)

Description

A standard Windows95 tree which may also be used to select multiple entries using the ‘Checked’ property.

Index – should an integer index into ...

Structure – which defines the tree labels, depth and optional image

The ‘Structure’ should be a nested text vector and a parallel column of level numbers with optional imageindex in column-3. The level numbers must start with level-0, but you may have as many 0-level items as you like. The levels must work down incrementally, but may step out in jumps, for example 0 1 1 2 3 1 2 2 0 1 is valid, but 0 2 2 1 2 4 0 1 is not.

Use the SetImage function to attach an ImageList (see the IL class) on creation. The optional 3rd column gives the positions of your icons in this list. Use 16 x 16 icons for preference and ensure that the ImageList is defined on the form before the tree! The optional 4th column is a boolean with 1 where the node should be expanded.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Editable | Bool |  | Item labels may be edited by the user with F2
Style | ManyOf |  |
3D | OneOf | ‘Recess’ | Border style
Index | User |  | Index of selected line
Structure | User |  | Tree structure [;vtv level {imageindex} {expanded} ]
Checked | User |  | Selected items (integer vector 1=Y 0=N ¯1=Some)
Propagate | Bool | 1 | Propagate selection up/down tree
Expanded | User |  | Which items are opened up (boolean vector)
DragSource | Bool |  | User can drag items off this control
DragMode | OneOf |  | Permitted drag operations
DropAccept | StringList |  | Accepts drag-over and drag-drop from these groups

Class-specific Events

IDC | Item double-clicked
DRAGOFF | Item dragged off the tree
DRAGOVER | Item draggged over the tree
DRAGDROP | Item dropped on the tree
EDIT | Item label edited by user
RMM | Right-mouse menu request

Class-specific Functions

AddChildren | Add item(s) as children of specific item
AddItems | Add same-depth item(s) after specific item
AutoExpand | Set Expand depth on refresh
CollapseAll | Curl up entire tree
CollapseItems | Collapse specified item(s)
DeleteChildren | Delete all children of specified item(s)
DeleteItems | Delete specified item(s) and their children
EnsureVisible | Ensure specific item visible
ExpandAll | Uncurl entire tree
ExpandItems | Expand selected item(s)
GetAncestors | Indices of ancestors of specified item (nearest to most distant)
GetChildren | Indices of first-generation children of specified item
GetDescendants | Indices of all children, grandchildren, etc., of specified item
GetFirstVisible | Return index of first visible item
GetItemDepth | Return depth of specified item(s)
GetItemImage | Return index of image of specified item(s)
GetSiblings | Indices of siblings of specified item
GetVisibleCount | Return number of visible items
SetFirstVisible | Scroll to make specified item the first one visible
SetImage | Attach image list
SetItemImage | Set image(s) associated with item(s)
ShowItem | Show specified item


CPro Turorial and Reference: TreeView - Checked Property

TreeView – Checked Property

This property can be used to allow the user to make multiple selections on the tree. Three built-in icons are used to show the ‘selected’ ‘deselected’ and ‘ambiguous’ states. If ‘propagate’ is true, a leaf node is always in state 1 or 0 – nodes higher up the tree will reflect the logical sum of the states of all their children (1 if all 1s, 0 if all 0s, otherwise ¯1). Changing the state of a higher-level node automatically switches all the descendants into the same state.


CPro Turorial and Reference: TreeView - DragSource Property

TreeView – DragSource Property

If this property is set to ‘true’ you will be able to drag items off the tree. You may wish to handle the DRAGOFF message which you can reject if it is not appropriate to drag this particular item.


CPro Turorial and Reference: TreeView - DropAccept Property

TreeView – DropAccept Property

This property sets the list of group ids from which the tree will accept drag-drops. You can set it to ‘*’ to accept dropped items from any control, including itself. Even if you accept items from a control, you can handle the DRAGOVER and DRAGDROP messages to selectively ignore particular items, or to reject drops on specific elements of this control.


CPro Turorial and Reference: TreeView - DRAGOFF Event

TreeView – DRAGOFF Event

Reported when the user attempts to drag an item from a tree which has the ‘DragSource’ property set to ‘true’. The message gives the selitems in force at the point when the drag begins – you may reject the message if it is not appropriate to drag this particular item, or you can re-assign ⍵ to place your own information here. This ‘token’ will be passed to any potential drop-targets in the DRAGOVER and DRAGDROP messages which will be sent to the targets when required.


CPro Turorial and Reference: TreeView - DRAGOVER Event

TreeView – DRAGOVER Event

Reported when the tree has at least one group in its ‘DropAccept’ list and an item from an accepted source is being dragged over it. The message reports (item-index in your ⎕IO)(token from drag source)(mode)(menu)(group1 of source)(group2 ...) as an n-element vector. In the message, mode is 0 for move, 1 for copy; menu is 0 for a normal drop, 1 for a menu request (right-button drag). You may reject the event – otherwise the item will be highlighted.


CPro Turorial and Reference: TreeView - DRAGDROP Event

TreeView – DRAGDROP Event

Reported when the object has at least one group in its ‘DropAccept’ list and an item from this source is dropped on it. The message reports (item-index)(mode)(menu)(token from drag source)(group1 of source)(group2 ...) as an n-element vector. You may ignore the event, but not reject it or modify the message format.


CPro Turorial and Reference: TreeView - EDIT Event

TreeView – EDIT Event

Reported when the text of a label has been changed by the user. The message has the item number and new text as a 2-element vector. If you reject the message, the change will not be accepted by the control.


CPro Turorial and Reference: TreeView - RMM Event

TreeView – RMM Event

Reported when the right-mouse button is released over an item, with the mouse having been moved less than the distance needed to initiate dragging. The message reports the item-index.


CPro Turorial and Reference: TreeView - AddChildren Function

TreeView – AddChildren Function

Adds one or more items immediately following a specified item. The first of the new items will be a child of the specified item.

  trObj ∇Do 'AddChildren' parentinx labels depth imageinx

where the arguments are:

parentinx | integer scalar, the index of the tree item that will be the parent of these new item(s).
 | A negative value sets the index relative to the last item in the control, so
 | 'Do 'AddChildren' ¯1 labels
 | adds the new items as children of the last item in the tree.
labels | vector of text vectors, the label for each new item.
depth | optional non-negative integer vector, the depth of each item relative to the first of these new items. If supplied, the first value in depth can be zero but must not be greater than any other value in the vector. The values in depth should comply with the depth vector conventions for a tree.
imageinx | optional non-negative integer vector, the image index in the ImageList of the control for each of the new items.

The shy result is an integer scalar, the index number of the first of these new children in the amended tree.


CPro Turorial and Reference: TreeView - AddItems Function

TreeView – AddItems Function

Adds one or more items immediately following a specified item. The first of the new items will have the same depth as the specified item.

  trObj ∇Do 'AddItem' peerinx labels depth imageinx

where the arguments are:

peerinx | integer scalar, the index of the tree item after which these new items will be inserted.
 | A negative value sets the index relative to the last item in the control, so
 | ∇Do 'AddItem' ¯1 labels
 | inserts the new items following the last item in the tree.
labels | vector of text vectors, the label for each new item.
depth | optional non-negative integer vector, the depth of each item relative to the first of these new items. If supplied, the first value in depth can be zero but must not be greater than any other value in the vector. The values in depth should comply with the depth vector conventions for a tree.
imageinx | optional non-negative integer vector, the image index in the ImageList of the control for each of the new items.

The shy result is an integer scalar, the index number of the first of these new items in the amended tree.


CPro Turorial and Reference: TreeView - AutoExpand Function

TreeView – AutoExpand Function

Sets the AutoExpandDepth property for the tree. When the Structure of the tree is refreshed, each branch of the tree is expanded to at least this depth.

  ⍺ ∇Do 'AutoExpand' depth

where depth is a non-negative integer scalar. The default value is 2.


CPro Turorial and Reference: TreeView - CollapseAll Function

TreeView – CollapseAll Function

Collapses all tree branches to the top level. Any subsequent expansion of a node restores its branches as they were prior to running CollapseAll.

  trObj ∇Do 'CollapseAll' 0

The shy result is always boolean 1.


CPro Turorial and Reference: TreeView - CollapseItems Function

TreeView – CollapseItems Function

Hides the children of selected items.

  trObj ∇Do 'CollapseItems' inx

where inx is an integer scalar or vector, the index number of one or more items in the tree.

The shy result is always 1.


CPro Turorial and Reference: TreeView - DeleteChildren Function

TreeView – DeleteChildren Function

Deletes all the children of one or more specified items.

  trObj ∇Do 'DeleteChildren' inx

where inx is an integer vector, the index number(s) of the parent item(s) whose children are to be deleted.

The shy result is an integer vector, the number of children deleted for each item in inx.


CPro Turorial and Reference: TreeView - DeleteItems Function

TreeView – DeleteItems Function

Deletes one or more specified items together with the children of each.

  trObj ∇Do 'DeleteItems' inx

where inx is an integer vector, the index number(s) of the item(s) to delete.

The shy result is an integer vector, the number of items, including children, deleted for each item in inx.


CPro Turorial and Reference: TreeView - EnsureVisible Function

TreeView – EnsureVisible Function

Scrolls and if necessary opens the tree to make the requested item visible.

  trObj ∇Do 'EnsureVisible' 35


CPro Turorial and Reference: TreeView - ExpandAll Function

TreeView – ExpandAll Function

Expands all tree branches.

  trObj ∇Do 'ExpandAll' 0

The shy result boolean scalar 1.

This is not the direct opposite of CollapseAll, which collapses branches at the root level only.


CPro Turorial and Reference: TreeView - ExpandItems Function

TreeView – ExpandItems Function

Expands one or more specified items to reveal its/their children.

  trObj ∇Do 'ExpandItems' inx

where inx is an integer scalar or vector, the index numbers of the items to expand. Note that each item is expanded only one level. To expand an entire branch, you must specify the index number of an item together with the indices of all its descendents:

  trObj ∇Do 'ExpandItems' inx, trObj ∇Do 'GetDescendants' inx

The shy result is always Boolean scalar 1.

See also GetDescendants


CPro Turorial and Reference: TreeView - GetAncestors Function

TreeView – GetAncestors Function

Returns the indices to all ancestors of the specified item.

  trObj ∇Do 'GetAncestors' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the indices of all the descendents of item inx, from the nearest to the most distant. It can be empty.

See also GetChildren, GetDescendants, GetSiblings.


CPro Turorial and Reference: TreeView - GetChildren Function

TreeView – GetChildren Function

Returns the indices of the next-generation children of a specified item.

  trObj ∇Do 'GetChildren' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the indices of all the children of item inx. It can be empty.

See also GetAncestors, GetDescendants, GetSiblings.


CPro Turorial and Reference: TreeView - GetDescendants Function

TreeView – GetDescendants Function

Returns the indices of the all the descendants of a specified item.

  trObj ∇Do 'GetDescendants' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the indices of all the descendants of item inx. It can be empty.

See also GetAncestors, GetChildren, GetSiblings.


CPro Turorial and Reference: TreeView - GetFirstVisible Function

TreeView – GetFirstVisible Function

Returns the index number of the first item visible at the top of the control.

  trObj ∇Do 'GetFirstVisible' 0

The result is an integer scalar, the index number of the first item visible at the top of the control.


CPro Turorial and Reference: TreeView - GetItemDepth Function

TreeView – GetItemDepth Function

Returns the depth of one or more items in the control.

  trObj ∇Do 'GetItemDepth' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the depth of each item. Where an element of inx points to a non-existent item, the corresponding element of the result contains ¯1.


CPro Turorial and Reference: TreeView - GetItemImage Function

TreeView – GetItemImage Function

Returns the image pointer of one or more items in the control.

  trObj ∇Do 'GetItemImage' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the image pointer of each item. Where an element of inx points to a non-existent item, the corresponding element of the result contains ¯1.


CPro Turorial and Reference: TreeView - GetSiblings Function

TreeView – GetSiblings Function

Returns the indices of the all the siblings of a specified item.

  trObj ∇Do 'GetSiblings' inx

where inx is an integer scalar or one-element vector, the index number of the item of interest.

The result is an integer vector, the indices of all the siblings of item inx. It can be empty.

See also GetAncestors, GetChildren, GetDescendants.


CPro Turorial and Reference: TreeView - GetVisibleCount Function

TreeView – GetVisibleCount Function

Returns the number of items visible in the control. This value is the number of fully visible (unclipped) rows in the control.

  trObj ∇Do 'GetVisibleCount' inx

The result is an integer scalar, the number of items visible in the control.


CPro Turorial and Reference: TreeView - SetFirstVisible Function

TreeView – SetFirstVisible Function

Tries to position a specified item at the top of the visible portion of the control, expanding items or scrolling the treeview control if necessary.

  trObj ∇Do 'SetFirstVisible' inx

where inx is an integer scalar, the index number of the item to position at the top of the visible portion of the treeview. A negative value indicates an item relative to the final item in the control, so a value of ¯1 ensures that the last item is visible.

The shy result is an integer scalar, the index of the number of the item that was previously at the top of the visible portion of the control.

It is not possible to scroll the treeview under program control such that there is empty space between the last item and the bottom of the treeview. This means that the topmost item in the control can only ever be nItems-nVisible where nItems is the total number of items in the control and nVisible is the number of items that are visible (see GetVisibleCount).

Use the ShowItem if it is necessary only to ensure that a specified item lies within the visible portion of the control.


CPro Turorial and Reference: TreeView - SetImage Function

TreeView – SetImage Function

Sets the ImageList property of the control

  trObj ∇Do 'SetImage' obj

where obj is a text vector or vector of text vectors, the name(s) of the bitmapped objects to use. The first name contains the set of bitmaps or icons that are pointed to by the ImageIndex property of each item in the treeview. The second object, if supplied, contains the set of bitmaps or icons that are pointed to by the SelImageIndex property of each item in the treeview.

The shy result is always Boolean scalar 1.


CPro Turorial and Reference: TreeView - SetItemImage Function

TreeView – SetItemImage Function

Sets the index of the image associated with one or more unselected TreeView item(s)

  trObj ∇Do 'SetItemImage' imagemap

where image is a two-element integer vector or two-column integer matrix, pointers respectively to the items (first element or column) and the image (second element or column).

The shy result is always Boolean scalar 1.


CPro Turorial and Reference: TreeView - ShowItem Function

TreeView – ShowItem Function

Ensures that a specified item is visible in the control, expanding items or scrolling the treeview control if necessary.

  trObj ∇Do 'ShowItem' inx

where inx is an integer scalar, the index number of the item to scroll into view if it is not currently visible to the user. A negative value indicates an item relative to the final item in the control, so a value of ¯1 ensures that the last item is visible.

The shy result is a Boolean scalar 1 if the control was scrolled to ensure the specified item was visible, 0 otherwise.

Use the SetFirstVisible if you must try to position a specified item at the top of the visible portion of the control.


CPro Turorial and Reference: Tabbed Subform (TSF)

Tabbed Subform (TSF)

Description

Designed as if it were a stand-alone form. You can call it (to see the effect) from the session, but normally you would use ∇Make to make all the subforms as a create (CR) action on the parent form.

CR: ∇Make¨dbx.sub1 dbx.sub2

By default, the tabs are labelled with the form caption, but the Tab label over-rides this. The Tab width data is optional, and can be used to set the detailed appearance of the tabs if required. If you omit this setting, the tabs will be sized to fit your captions.

Class Property Table

Name | Type | Default | Description
Locals | NameList |  | Local variables
Tab label | Runtime |  | Tab Label (deflt is form caption)
Alignment | Oneof | ‘Top’ | Tab positioning (Top, Left etc.)

Class-specific Events

LMT | Left mouse on tab
RMT | Right-mouse on tab

Class-specific Functions

ToFront | Bring this subform to the top
AtFront | Is this subform at the front


CPro Turorial and Reference: Tabbed Subform - LMT Event

Tabbed Subform – LMT Event

This event is reported on a Tabbed Subform when the user clicks the left-mouse on any of the dialogue tabs.


CPro Turorial and Reference: Tabbed Subform - RMT Event

Tabbed Subform – RMT Event

This event is reported on a Tabbed Subform when the user clicks the right-mouse on any of the dialogue tabs. It is most likely to be used to put up a popup menu.


CPro Turorial and Reference: Text entry (TX)

Text entry (TX)

Description

Single-line text edit. Text var is shown in the box and updated when the focus leaves the field for any reason.

Caption will generate a label either above, or to the left if Style includes ‘side’.

Format var may be set to ‘XX...XX’ to fix maximum length, and to force optional uppercase translation. By default it clears trailing blanks from the returned data.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Accelerator | String |  | Hotkey (e.g. Ctrl+S)
Style | ManyOf |  |
Format | Runtime |  | Format (e.g. ‘XXXX’ is u/c 4 long)
Text | User |  | Text variable
DTB | Bool | 1 | Delete trailing blanks
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton

Class-specific Events

HR Help Request


CPro Turorial and Reference: VCR Buttons (VC)

VCR Buttons (VC)

Description

A set of four small square buttons in a recess, to look like the ‘rewind’ ‘reverse’ ‘forward’ and ‘end’ buttons on a Video Recorder. Use this to page through layers of data in a 3D spreadsheet, or for left-right paging in a column-based editor.

It expects a ‘Stop points’ variable as a numeric list (default value 1..99) and a data variable of a numeric singleton which is an index into the list. The four buttons set the data variable to ‘first’, ‘previous’, ‘next’ ,’last’ respectively.

Note that the list of ‘Stop points’ need not be in ascending sequence.

If nothing else catches <Ctrl+Home> <PgUp> <PgDn> and <Ctrl+End> these keys trigger the appropriate buttons.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
Index | User |  | Current Index
Stop points | Runtime |  | Stop points list


CPro Turorial and Reference: Vertical Splitter (VSB)

Vertical Splitter (VSB)

Description

Emulates a vertical separator by resizing the objects to its left and right. Takes the group ids of all the objects you want it to manage (in any order). This is most likely to be used to emulate the Windows95 Explorer style where you have a tree-control down the left of your form and a selection of other controls to the right.

Consider using the Containing Region here to reduce the number of objects handled by the splitter.

Class Property Table

Name | Type | Default | Description
Controls | Stringlist |  | Objects to split (group ids)
Hidden | Bool |  | Used to constrain other splitters
Limits | Runtime |  | Closest Approach to edge (left,right)
Where | User |  | Current horizontal position
Active | Runtime |  | Boolean singleton

Class-specific Functions

MoveTo Move splitter to this column (pixel position)


CPro Turorial and Reference: Vertical Separator (VSEP)

Vertical Separator (VSEP)

Description

Simple ruled line to segregate controls. Will always draw exactly vertical.

Class Property Table

Name | Type | Default | Description
3D | OneOf | ‘Groove’ | Visual style (groove or ridge)


CPro Turorial and Reference: Web Browser (WB)

Web Browser (WB)

Description

A very thin wrapper on the MS WebBrowser control. Has one property ‘Navigate’ which takes the file or URL to show, and reports a ‘HINT’ event when the mouse is over something interesting.

The user can navigate completely normally, and the standard MS right-mouse menu behaves as you would expect.

May be used to render a RainPro chart in any format which a browser can display. VML, SVG, PDF are possible.

Class Property Table

Name | Type | Default | Description
Navigate | User |  | URL or filename to show
PostScript | Runtime |  | Graphic to draw (PostScript vector)
Multipage | Runtime |  | Boolean – Preview all pages (PDF only)
Page No | Runtime |  | Page number (integer)
RenderAs | Runtime |  | How to render – 1=vml 2=svg 3=pdf 4=xml
Scaled | Runtime |  | Scale chart to fit window
Active | Runtime |  | Respond to updates and signal events
Source | Runtime |  | XML or plain text source to pass through
Offline | bool | 1 | Start in Offline mode
VMPath | txt | ‘#.vml’ | Path to VML renderer
SVPath | txt | ‘#.svg’ | Path to SVG renderer
PDPath | txt | ‘#.pdf’ | Path to PDF renderer

Class-specific Events

HINT Hint to display

Class-specific Functions

Back | Return to previous page
Forward | Go to next page
Stop | Cancel navigation
Reload | Reload page


CPro Turorial and Reference: Yes/No choice (YN)

Yes/No choice (YN)

Description

A single ‘tick the box’ object.

Boolean should be a boolean singleton; the box is ticked when this is 1.

Class Property Table

Name | Type | Default | Description
Hint | String |  |
ToolTip | String |  |
Style | ManyOf |  |
Align | OneOf | ‘Right’ | Caption placement (left or right)
Boolean | User |  | Boolean (boolean singleton)
Visible | Runtime |  | Boolean singleton
Active | Runtime |  | Boolean singleton


Reference: Standard Class Functions

All the shipped classes support this set of standard functions.

  • Caption
  • Close
  • Disable
  • Enable
  • Fns
  • Hide
  • Ready
  • Set
  • Show
  • Wait


CPro Turorial and Reference: Caption

Caption

Change an Object’s Title

Sets the caption of any object.

obj #.CPro.Do 'Caption' 'New Caption'


CPro Turorial and Reference: Close

Close

Remove any Object

This removes the object (unconditionally). You can set a ‘Destroy‘ event on its behaviour table to clean up, but you cannot prevent it from closing.

#.CPro.Do 'Close' obj


CPro Turorial and Reference: Disable

Disable

Deactivate Object

Accepted by all objects. Prevents the object from reporting any events, and greys out the text (or bitmap) on action buttons. Any associated captions are also greyed out. Command syntax is:

obj←⊃#.CPro.Id 'name'
obj #.CPro.Do 'Disable'

Bitmaps on action buttons are greyed out like this.
When you disable a VCR group, the entire set is inactivated (and greyed out) as a unit.

Used on forms to disable (i.e. grey out) menu items by name.

fm #.CPro.Do 'Disable' 'Undo'  ⍝ Nothing to undo

Disabling menu sections

To grey out an entire menu section use the section name (with the enclosing [ ]) as the argument to CPro.Do ....

fm ∇Do 'Disable' '[edit]'

... this will grey the entire [edit] section. Note that the section name is case-sensitive.

See also ...

Enable


CPro Turorial and Reference: Enable

Enable

Activate Object

Accepted by all objects. Normally, objects are enabled when created, but you may have temporarily disabled them in your program. This command restores them to normal.

When used on parent forms, it will enable a ‘greyed’ menu option by name.

  fm CPro.Do 'Enable' 'Undo'  ⍝ Allow undo when sensible!

Enabling menu sections

To ungrey an entire menu section use the section name (with the enclosing [ ]) as the argument to CPro.Do ....

fm ∇Do 'Enable' '[edit]'

... this will open up the entire [edit] section. Note that the section name is case-sensitive.

See also ...

Disable


CPro Turorial and Reference: Fns

Fns

List Functions from Object

This lists all the available commands on any object or class.

      +ma #.CPro.Do 'Fns'   ⍝ Functions from the matrix
Info Move

Note that the list does not include generic commands such as ‘Show’ and ‘Hide’ which are implemented on all objects.

Technical Note

If you add your own functions to a class, you should include them in the [Public Functions] section of the class specification to have them listed here.


CPro Turorial and Reference: Hide

Hide

Make Object Invisible

Accepted by all objects.The object (and associated objects such as its caption) are no longer visible, and the object does not accept any events. Command syntax is:

obj←⊃#.CPro.Id 'name'
obj #.CPro.Do 'Hide'


CPro Turorial and Reference: Ready

Ready

Cancel Wait Cursor

To cancel the wait cursor on the application:

'.' #.CPro.Do 'Ready'

.... or on a specific form ...

fm #.CPro.Do 'Ready'


CPro Turorial and Reference: Set

Set

Setting any Object Property

The general case of this is simply a cover on the Dyalog ⎕WS command:

cap #.CPro.Do 'Set' 'FCOL' (128 0 0)

Progress Bar

Sets the percent complete, or ‘n of m’ message in a progress bar, and updates the shaded area to match.

pbar #.CPro.Do 'Set' 67     ⍝ Sets to 67%
pbar #.CPro.Do 'Set' 12 28  ⍝ Sets to '12 of 28'


CPro Turorial and Reference: Show

Show

Make Object Visible

Accepted by all objects. Normally, objects are visible when created, but you may have temporarily hidden them in your program. This command restores them to normal, along with any captions or other associated objects.

See also: Hide command


CPro Turorial and Reference: Wait

Wait

Set Hourglass Cursor

To set the entire application into a waiting state, use

'.' #.CPro.Do 'Wait'

To set a form into a wait state ...

fm #.CPro.Do 'Wait'

In addition, you may temporarily inactivate all the controls on the form by specifying:

fm #.CPro.Do 'Wait' 1  ⍝ Long wait

They are restored to their previous state by ...

fm #.CPro.Do 'Ready'


Reference: Modifying and Building Classes

This section shows you how to create and use your own classes alongside those shipped with CPro.

  • The Causeway Class Library
  • Adding a New Class Library
  • Adding a New Class
  • Removing a Class
  • The Specification Format
  • The Bitmap Property
  • The Metafile Property
  • The Hidden Property
  • Class-Specific Property Types


CPro Turorial and Reference: The Causeway Class Library

The Causeway Class Library

You will find all the supplied classes as child namespaces off #.Class, and you can use the GetCls and SaveCls functions in this namespace to import classes from file and to save any changes you make. These functions will accept a full pathname, but the file path defaults to the path specified in your causeway.ini [paths] section, for example:

[Paths]
Class=c:\apl\causeway
Classdoc=d:\products\common\cprohlp

Note that you can save the class specification as a separate ASCII text file using SaveSpec and GetSpec if you prefer to edit this variable using an external text editor. These files are placed by default into the ClassDoc directory.

If you need to upgrade an existing class (for example the TreeView) you should use the same function:

)cs Class
GetCls 'TR'   ⍝ Import it from file
#.CPro.Build  ⍝ Register it with the CPro engine

The call to #.CPro.Build is essential whenever you add, delete or modify a class.

You can use the simple utility Classes to list all the classes available in a given class library. Note that this will not ‘see’ a namespace as a class until Class.ParseSpec has been run on it at least once to create the appropriate variables from the specification.

Contents of a Class Namespace

All classes contain the same basic set of standard functions:

  • Create – called initially to make the object
  • Refresh – called whenever a runtime property changes, to refresh the control
  • Read – called when the user changes the control to return the new value
  • Destroy – called when the control is deleted

There may be other functions, typically callbacks such as onKeyPress, which only appear in the classes that require them. You will also find a small number of variables, all but one of which are generated automatically by CPro.Build and can be ignored. Everything Causeway needs to know about the class is stored in a text variable called specification, which has the standard form:

[Design]
Name=Action Button
Type=Button
... for the designer to use
[Properties]
... property names and types
[Events]
... any class-specific event codes
[Cue Card]
... instructions for use
[QA]
... testing script (optional)
[Release Notes]
... optional but recommended

You can edit this with the normal Dyalog editor when you need to add or modify the class definition, but remember to run Class.ParseSpec if you change the properties or custom events. This generates working copies of the [Properties] and [Events] sections for fast access by Causeway. See the notes on the specification format for full details.


CPro Turorial and Reference: Adding a New Class Library

Adding a New Class Library

It is strongly recommended that you put all your own classes (which may be simple modifications to existing CPro classes) in a separate library. This allows you to upgrade your copy of CPro by a simple:

)xload myws
)copy cpro CPro Class Designer
#.CPro.SetClassPath '#.Class' '#.MyClasses'
#.CPro.Build

... otherwise you could easily overwrite your modifications with the standard class definitions.

Copying the Supplied Template

CProQA is shipped with a prototype class library called UserTemplate (this is in ⎕IO=1, ⎕ML=1). You should make a namespace copy and add this to the list of known libraries ...

 )copy cproqa UserTemplate
 'MyClass' ⎕NS ⎕OR 'UserTemplate'
 #.CPro.SetClassPath '#.MyClass' '#.Class'

In general, you should put your libraries first in the list so that if you copy and modify existing CPro classes, your copies will override the standard ones. You can quickly revert to the shipped classes by reversing the order of the libraries.


CPro Turorial and Reference: Adding a New Class

Adding a New Class

This assumes you have already added a new class library, called MyClass. To add a new class, simply copy the Template namespace in the normal way, run ParseSpec to make a default set of working variables, edit the specification to give it a suitable name and type, and run #.CPro.Build to make it known to Causeway. At this point you should see it in the designer (one of the list of new objects) with the sample property set.

 )cs #.MyClass
 'new' ⎕NS ⎕OR 'Template'  ⍝ Add a class called 'new'
 ParseSpec 'new'           ⍝ Define property tables
 #.CPro.Build              ⍝ Add it to the list of classes

You may like to save it on an external file as well as maintaining a workspace copy:

 SaveCls 'new'      ⍝ Save class definition on file new.cls

N.B. The Template class will run as a simple edit field – modify the Create, Refresh and Read functions as required. All the code assumes ⎕ML=1 and ⎕IO=1, but Causeway will run with classes in any ⎕IO,⎕ML configuration.


CPro Turorial and Reference: Removing a Class

Removing a Class

The Causeway class library has been constructed so that there are no dependencies between classes, so you can safely remove any class you are not using in your application.

)cs Class
)erase AC HP TM
)cs #
CPro.Build

There is a sample function (called enum) in the dbx namespace which lists all the classes which you need to build your current collection of dialogue boxes.

)cs Class
⎕EX Classes~#.dbx.enum
Classes
AC EN FM QT TX
)cs
#.CPro.Build

In general, you should reduce the class library to a reasonable working set for each application. This saves on workspace and reduces the number of menu entries shown in the Designer when you add a new object to your form.


CPro Turorial and Reference: The Specification Format

The Specification Format

The class specification is used by #.CPro.Build to construct a number of class variables detailing its events, properties etc. It is also used by the Designer to determine how the class appears in design mode, and to offer the developer simple on-line help (the ‘Cuecard’ section). It may be erased from the workspace in a runtime system, and you may choose to reduce it to a bare minimum in classes where no further modifications are planned.

It is structured as a vector of text vectors (vtv) in standard .INI form with the following sections.

Required Section for Use by the Designer

The Name entry is required, all other keywords may be omitted if not applicable. Classes with no Type specified appear at the top level on the ‘New’ object menu in the Designer. If Style is omitted the object will be designed as a simple captioned rectangle. Other built-in styles such as ‘Button’ may be appropriate, or you may use a custom design function (see the CB class for an example) if required.

[Design]
Name= ⍝ appears in designer right-mouse menu
Type= ⍝ used to group controls in the designer
Style= ⍝ omitted, or one of ...
  Button
  Group
  Form
  Placeholder ⍝ such as MRU class
  Custom ⍝ needs Design function in class.
Sizeable=0 ⍝ Display without sizing handles.
Transparent=1 ⍝ ignores mouse down except on edges
Size=h,w ⍝ fix size at creation
  ⍝ N.B. either h or w may be zilde to allow sizing in that dimension only
Colour=R G B ⍝ colour of placeholder
Pattern=8 x 8 bitmap ⍝ background bitmap for forms
GridColour=R G B ⍝ sets colour of form background bitmap
RightMouseHandler=myfn  ⍝ Over-ride for standard designer menu
LeftMouseHandler=myfn  ⍝ Over-ride for locator
Parent=1 ⍝ required for objects that can be parents

Most of the other settings are not frequently used – browse some classes to see how they affect the behaviour of the class in design view. For example the HSEP and VSEP are only sizeable in one direction, the TI uses a placeholder style, and the PL is transparent to mouse clicks, so that other objects may be added within it.

Functions Intended for use by the Application

Many classes have so-called ‘Public’ functions which are intended for application use. For example the TreeView has an extensive library of calls to add and remove branches, list the children of a node, and so on. For each entry in this section, you may add a matching entry for the function itself. This will be used in compiling the help file for the class, and will be shown by the designer if available.

[Public Functions]
FirstFn arg  ⍝ First Function
Second 'abc' ⍝ Second function
[FirstFn]
This takes a scalar integer and ...

It is good to show the sample syntax for the function, as this is used in the Designer when you use the ‘Paste Function ...’ option in the Event-Table editor.

Other Sections Used by Class.ParseSpec

For a class to operate correctly, #.CPro.Make must add the correct event handlers so that actions which you enter in the Behaviour table in the designer are fired when the event occurs. For example if you want the class to support context-sensitive help (the user may hit <F1> in an edit field) then define any free event number (3000 and above by convention) as an HR event and have a KeyPress handler queue this event on the object when it detects the correct keypress. You can have as many of these class-specific ‘dummy’ events as you require, but make sure they have unique numbers within any one class.

[Events]
HR=3001 ⍝ Help Request

Class properties are used by the Designer to build the ‘property-watcher’, and may be fully defined at design time, or may give an APL expression which is re-evaluated whenever required to update the control. For example:

[Properties]
Text:        User    ⍝ The text you typed
Selection:   User    ⍝ The selected bit
Text Colour: Runtime ⍝ A valid colour triple ...
Readonly=0:  Bool    ⍝ Readonly field

Property-types User and Runtime are special, as they always take an APL expression as the value. See the notes on Using the Designer for more details. The other types are fixed when you design the control and may be chosen from:

  • Bool
  • Text, Txt, String
  • APLText, APLString
  • Int
  • Float
  • OneOf <vtv> or <tm>
  • ManyOf <vtv> or <tm>
  • Colour,Color
  • Hidden
  • larg YourFn rarg (see below)

If you need a type which is not easily classified as one of these (for example a numeric pair) then you may define your own maintenance function for it in the class. See Class-specific property types for more details.

[Read Events]
Text=36          ⍝ User property 1
Selection=2 3003 ⍝ User property 2

You must include an entry on the Read-Events list for every User property in the class. This list is used by Causeway to fire the Read function in the class whenever the appropriate event fires. You may choose to have the Read function run on several events, and these events may be standard Dyalog events (for example 36 is ‘Changed’) or may be queued from within the class. You may only give the event numbers here.

Optional Sections for Additional Class Documentation

You may add as many other sections to the specification as you need. If a section called [Cue Card] exists it will be used by the designer to offer pop-up help on the class. You may include HTML tags here – for the moment they will be screened out by the Designer, but they are used in the helpfile compilation and may be shown on the cue-card in a future release.

[Cue Card]
Shown in the Designer.
May spread over several lines.
[Release Notes]
Release notes here
[QA]
Script to be run by Class.Seatrial to check out the class.

Use Class.SaveSpec 'cls' to save the specification as an ASCII text file. As an alternative to the standard Dyalog editor, try Class.Ted, e.g.

#.Class.Ted 'AC.specification'

... which provides a simple word-wrapping text editor.


CPro Turorial and Reference: The String Property

The String Property

This is used to specify a design-time property (such as a caption) which is a simple text vector, and should not be displayed with an APL font. It is represented in the Designer as a simple edit field with a ‘more’ button at the right-hand edge.

By default this pops up a simple notepad field; to invoke a specific service function, simply set the property as “myprop : string ‘foo’ “ – this will run foo in the class namespace (passing it the string, and expecting a string result) from the ‘...’ button for string types. The shipped ‘AC’ class illustrates the effect for the ‘Accelerator’ property which can now be entered by simply pressing the appropriate key combination.


CPro Turorial and Reference: The APL-format Text Property

The APL-format Text Property

This property is shown by the Designer as a simple edit field using an APL font. All hot keys are disabled here to permit use of the standard Dyalog APL keyboard.


CPro Turorial and Reference: The StringList Property

The StringList Property

This may be used wherever a property requires a list of words, for example the built-in ‘Groups’ property requires a list of group ids to which the object belongs.

It is shown in the Designer as a comma-separated list in a standard edit field, with a ‘Zoom’ button at the right. By default, this splits the list and shows each word on a line of its own in a popup edit window.

To invoke a specific service function, set the property as “myprop : stringlist ‘foo’ “ – this will run foo in the class passing it a vector of text vectors, and expecting a similar result.


CPro Turorial and Reference: The APL Namelist Property

The APL Namelist Property

This type is used by Causeway for the ‘locals’ property, where a list of APL names is required. It shows the names in an APL font, and all hot-keys are ignored to make it possible to enter APL expressions using the normal Dyalog keyboard. It has a ‘Zoom’ button to expand the list into a popup edit field with each name on a separate line.


CPro Turorial and Reference: The Numeric List Property

The Numeric List Property

This is shown in the Designer as a simple edit field. The user may enter any number of blank-separated values which are stored in the dialogue definition as numbers.


CPro Turorial and Reference: The Integer Property

The Integer Property

This property is shown in the Designer as a simple edit field, with a numeric field type, no decimal places. It has a simple ‘spin’ behaviour – use the up/down arrow keys to adjust the value.

To see some examples of this property, look at the Spinner or Label classes.


CPro Turorial and Reference: The Floating Point Number Property

The Floating Point Number Property

This property type shows in the Designer as a simple edit field which accepts all valid numbers. It takes a single number only – see the NumList type if you need to maintain a vector.


CPro Turorial and Reference: The Boolean Property

The Boolean Property

This is used to maintain ‘Yes/No’ style properties, for example the ‘Delete trailing blanks’ selection on an edit field. It shows in the Designer as a drop-down with the options ‘True/False’ and maintains the value in the dialogue box as a boolean scalar.


CPro Turorial and Reference: The Single-Select Property

The Single-Select Property

This property type is used to choose one item from a list of valid values supplied as the right argument to the type name in the class specification. For example:

Compression : OneOf 'None' 'Low' 'High'  ⍝ Algorithm

You may give a default value, which should be one of the valid entries ...

Compression='Low' : OneOf 'None' 'Low' 'High'  ⍝ Algorithm

... and you may hold the list as a variable in the class namespace ...

Compression : OneOf ∆options ⍝ Algorithm

Note that the expression giving the default value is executed by Class.ParseSpec in the class namespace when you run CPro.Build. The expression giving the option list is executed by the designer whenever you switch focus to an object of that type, causing the property-watcher to rebuild itself.


CPro Turorial and Reference: The ManyOf Class Property

The ManyOf Class Property

This property type is used to choose several items from a list of valid values supplied as the right argument to the type name in the class specification. For example:

Garnish : ManyOf 'Lettuce' 'Onion' 'Peppers'  ⍝ Salads

... or you may hold the list as a variable in the class namespace ...

Garnish : ManyOf ∆salad ⍝ Salads

The expression giving the option list is executed by the Designer whenever you switch focus to an object of that type, causing the property-watcher to rebuild itself. It may be a simple list (vector of text vectors) or a two-column matrix giving short codes and a longer description. In this case the Designer will show the longer description in the popup-selection but store the short code in the dialogue box.


CPro Turorial and Reference: The Colour Property

The Colour Property

This property type maintains a three-element RGB setting using the standard Windows color-select dialogue. It shows the RGB values on the button in the property-watcher in the chosen colour.


CPro Turorial and Reference: The Bitmap Property

The Bitmap Property

Shows in the designer as a simple text field with a ‘Browse’ button at the right-hand end. This offers the developer a selection of files of type ‘*.BMP’ when pressed.


CPro Turorial and Reference: The Metafile Property

The Metafile Property

Shows in the designer as a simple text field with a ‘Browse’ button at the right-hand end. This offers the developer a selection of files of type ‘*.WMF’ when pressed. The class whould normally set this as its ‘picture’ property on creation.


CPro Turorial and Reference: The Runtime Property

The Runtime Property

Runtime properties are maintained by a special dialogue supplied by the CPro Designer. This maintains a two-column matrix structure with the APL expression to be executed, any dependencies and any pre-refresh code to be run before the expression is evaluated. See Using the Designer for more details.


CPro Turorial and Reference: The User Property

The User Property

User properties are maintained by a special dialogue supplied by the CPro Designer. This maintains a two-column matrix structure with the APL expression to be executed, any dependencies and any pre-refresh, validation or post-update code to be run before/during/after the expression is evaluated. See Using the Designer for more details.


CPro Turorial and Reference: The Behaviour Property

The Behaviour Property

The behaviour property is maintained by a special dialogue supplied by the CPro Designer. This maintains a four-column matrix structure with the event code, two APL expressions to be executed, and any names to be broadcast after the expression is run. See Using the Designer for more details.


CPro Turorial and Reference: The Hidden Property

The Hidden Property

Properties with type ‘hidden’ are stored with the object, but are not shown on the property browser by the Designer. They can be used to store any array you choose, and may be maintained as a side effect of other (visible) properties. For example you might make a grid class where all the interaction took place by means of right-mouse menus directly run from the visible grid. You would replace the standard right-mouse menu with your own handler function and use this to update entries in a hidden property (say ‘gridfmt’) which could have any structure and inner complexity you choose.

This requires 3 service functions from the Designer ....

Designer.GetPropVal
takes the object id on the left and the property-name on the right. It will return the current value of the property, or the default value from the class if it has not yet been set.
Designer.SetPropVal
takes the id on the left and a two-element vector giving the property-name and new value on the right. Note that no check is made here whether or not this is a known property – it is simply stored with the object and saved with the dialogue definition on exit. If you reset a property to its default value, it is removed from the object definition.
Designer.ForceRedraw
This is monadic – it takes an object id and gets the object redrawn and the Property-browser updated.

For more details on replacing the standard menu actions, see the notes on Custom Properties in the next section..


CPro Turorial and Reference: Class-Specific Property Types

Class-Specific Property Types

When you need to maintain a design-time property which is not one of the standard types (txt, num etc.) you should provide a function in the class namespace with the following syntax conventions:

res←old MyFn options;new

The Designer will call this with the current value of the property on the left and the function argument on the right (will be passed as '' if none is given). The function should prompt the user for a new value and return it as the second element of the result. If the first element is <1> the Designer will then store this against the property in the dialogue-definition, unless it matches the default value. If the first element is <0> the developer hit <Cancel> and the old value will be left in place. A typical entry in the specification would be:

Limits=3 4  : Constrain 10 200 ⍝ Limits on position

Here is a very old-fashioned approach to writing such a function:

res←old Constrain list;new
⍝ Modify (r,c) pair (always accepts change)
 'The old value is ',⍕old
 'Please enter a new value in the range ',⍕list
 new←2↑⎕
 'The new value will be ',⍕new
 res←1 new

The Designer will simply show a button labelled with the property name (or the current value if set). When pressed, this will run your function:

The old value is 2 3
Please enter a new value in the range 10 200
⎕:
      3 4
The new value will be 3 4

... and the property will be modified. Of course you can use #.CPro.Call here with a standard Causeway form to maintain a more complex property – use the return value from the call to set the first element of the result of the property-maintenance function.

Replacing the standard mouse handlers

Custom classes can set up their own mouse handlers to replace the standard menu offered by the Designer or the standard locator behaviour. A typical use would be in a class such as a grid or chart, where you wanted to modify selected details (like the gridlines, or the font of the chart heading) directly from the object in design mode. To replace the standard right-mouse menu with your own behaviour, you must first add an entry into the [Design] block of the specification to name your handler function:

[Design]
RightMouseHandler=SetProps  ⍝ My menu call

This should be Dyadic, result-returning and conform to:

Left Argument
The integer unique id of the object in the Designer
Right Argument
The standard mouse message
Result
1=”Event handled”; 0=”Not interested – use the default menu”

This allows you to check whether the mouse was over some interesting detail, and use your menu if so. Otherwise just return 0 and the Designer will go ahead with its normal menu. If you want to update some values in a hidden property, you will need the id to pass as argument to the SetPropVal call in the Designer.

See the UserTemplate.Template class for an example function ‘MyPopup’. A possible use for this would be a ‘chart’ object where you wanted your own menus on ‘hot’ areas like headings, but the designer gets to put up the normal menu when you hit the chart background.

The function ‘MyMove’ shows how you can modify the normal locator behaviour.


Reference: Event Reference

This section lists all the events which are reported by the various classes. These are generally passed through directly from Dyalog, so please refer to the Dyalog documentation for more information.

  • Mouse Down (MD)
  • Mouse Up (MU)
  • Mouse Moved (MM)
  • Double Click (DC)
  • Item Double Click (IDC)
  • Drag Drop (DD)
  • Key Pressed (KP)
  • Configure (CF)
  • Exposed (EX)
  • System Close (SC)
  • Iconified (IC)
  • Changed Data Event (CD)
  • Scrolled (SR)
  • Got Focus (GF)
  • Lost Focus (LF)
  • DDE Change (DE)
  • Timer Event (TI)
  • Help Request (HR)
  • User Defined (US)
  • Created (CR)
  • Destroy (DS)
  • Validation (VL)
  • Post Creation (PC)
  • Post Update (PU)
  • Close Request (CL)
  • Pre-refresh (PR)
  • Refresh Completed (RC)


CPro Turorial and Reference: Mouse Down (MD)

Mouse Down (MD)

The user depressed one of the mouse buttons over the object. This can be used to start a ‘rubber-band’ locator, or offer a ‘right-button’ menu on the object. The right button can be checked for with:

MD: 2=⊃⍵: ⍝ Right button pressed

The first two elements of the message give the [row col] position in the co-ordinate system of the object (usually pixels).

See also ... Mouse Up


CPro Turorial and Reference: Mouse Up (MU)

Mouse Up (MU)

A mouse button was released over the object. In Dyalog/W it is always a good idea to trap this event if you trapped Mouse Down. It should be entered in the ‘Behaviour’ table in the Designer, with the APL-code column left blank.


CPro Turorial and Reference: Mouse Moved (MM)

Mouse Moved (MM)

The mouse was moved over the object. The exact position is reported in the event message:

 MM:pos←⍵[1 2]

... except on RECT objects (in Dyalog/W) where it is always (0 0).

A stream of these events is reported, so it is important to keep the processing load small on any event-handler you add here.


CPro Turorial and Reference: Double Click (DC)

Double Click (DC)

A mouse button was clicked twice in quick succession over the object. On the main form, this is a shortcut for reducing the form to its minimum size, and returning it to its designed size.

This is conventionally used to signal a confirmation in objects such as the scrolling list; a single click selects a row in the list, a double-click selects and ends the dialogue. To do this, use a Behaviour table entry such as

DC: #.CPro.Return selected

to terminate the dialogue and return the value of local variable ‘selected’ to the calling function.


CPro Turorial and Reference: Item Double Click (IDC)

Item Double Click (IDC)

This is signalled to the TreeView and ListView when the user double-clicks an item in the tree or list. The value of ⍵ gives:

  1. Item number – The index of the item
  2. Mouse button
  3. Shift state – Sum of 1=shift key, 2=Ctrl key, 4=Alt key
  4. Position – Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon) or 4 (over the label)


CPro Turorial and Reference: Drag Drop (DD)

Drag Drop (DD)

This is reported when a dragged object is released on another object. It can be used to allow sorting of a list of names, where a set of draggable labels is re-ordered by the user.

Note that the ‘dropped’ object is identified by the first element of the event message:

  DD:obj←⊃⍵   ⍝ Find out which object was dropped


CPro Turorial and Reference: Key Pressed (KP)

Key Pressed (KP)

The user either typed something into the object, or used a cursor move or function key within it. Many objects (see below) already handle this event, so be careful that you do not disable built-in behaviour when you specify it in the Behaviour table for the object.

Built-in Key Press Handlers

  • Numeric Field – allows numbers only and restricts length
  • Text Entry – optional upper-case and restricted length
  • Date Entry – restricted chars (digits + delimiters)
  • Notepad – catches ‘Enter’ and starts a new line
  • Text Matrix – moves the active cell around the grid


CPro Turorial and Reference: Select Event (SL)

Select Event (SL)

This event is triggered on buttons when you press and release the left mouse button over the object. It is triggered on other objects (like list boxes) by clicking the mouse on an entry, or moving the highlight with the keyboard.

Normally, this is used on an action or tool button to run some code ...

SL : DeleteAllData : ∆data

... and so on.


CPro Turorial and Reference: Configure (CF)

Configure (CF)

This event is reported whenever any object moves or changes size relative to its parent. It might be used to re-position some controls on a form (if the standard ‘Attach’ behaviour is insufficient), to move related forms, and so on.

The message gives the new position and size of the object, but note that at the point the event is reported, the object has not yet been moved/resized so if you use ⎕WG 'Posn' 'Size' you will get the old values.


CPro Turorial and Reference: Exposed (EX)

Exposed (EX)

Part of the object (which had been covered by another window) has come back to the front. You should only need to handle this if you use un-named graphics, for example drawn on a backcloth. These will need to be explicitly redrawn after an expose.

N.B. This event is used by Causeway on the ListView to detect a drag-selection and hence to trigger a read of the ‘Indices’ property.


CPro Turorial and Reference: System Close (SC)

System Close (SC)

This is reported on the main form when the user requests ‘Close’ from the system menu. It signals a ‘Close Request’ event which the user may reject (assuming that it has been specified on the form’s Behaviour table), and thus prevent the form from closing.

It is often used from Menus to ask a form to close itself ...

E&xit:#.CPro.Post 'SC'

... this causes the form to queue a ‘SC’ to itself.

Please do not put your own actions on this, or if you do catch it, ensure you end your function with CPro.Destroy objname to remove the object cleanly.

To check and possibly reject a close request, you should use the CL event instead.


CPro Turorial and Reference: Iconified (IC)

Iconified (IC)

This is reported when the form is about to be minimised, restored, or maximised. It is used by the main form to ensure all child objects get resized automatically on a ‘maximise’ as well as a ‘resize’.


CPro Turorial and Reference: Changed Data Event (CD)

Changed Data Event (CD)

This event is reported on text fields when the field ‘loses focus’, after some data has been changed by the user. Typically, this occurs when tabbing out of the field, or when an action button is pressed.

This is used by Causeway for the majority of text-based controls to update the ‘Text’ property. Do not add your own behaviours here unless you are very sure what you are doing!


CPro Turorial and Reference: Scrolled (SR)

Scrolled (SR)

The object was scrolled. Scroll bars and Parameter bars use this as their prime source of data.


CPro Turorial and Reference: Got Focus (GF)

Got Focus (GF)

The object just received the input focus, either from a mouse-click or with the Tab key. Many objects (such as the Numeric Edit) catch this and select the text in the field automatically. If you don’t want this behaviour, just add an empty entry to the Behaviour table for the object.


CPro Turorial and Reference: Lost Focus (LF)

Lost Focus (LF)

The object no longer has input focus. Text fields generally use this to deselect text when the user leaves the field.


CPro Turorial and Reference: DDE Change (DE)

DDE Change (DE)

Reported on the main form only. This is signalled when some data changes at the far end of a DDE link.


CPro Turorial and Reference: Timer Event (TI)

Timer Event (TI)

Generated by the ‘Timer’ object at intervals set by its data property.

A good use of this is to kill a banner form after (say) 4 seconds. Simply add a timer to the form with an interval of 4000, and in the Behaviour table for the timer, specify:

TI :  : CPro.Return ⍬

Timers can also be used to update time-of-day fields etc.


CPro Turorial and Reference: Help Request (HR)

Help Request (HR)

Signalled by most text-entry objects when the user presses the <F1> key. The application will typically use this information to display context-sensitive help information for the field.


CPro Turorial and Reference: User Defined (US)

User Defined (US)

This event is intentionally left free for ad hoc use.


CPro Turorial and Reference: Created (CR)

Created (CR)

All objects report this event on creation, but before any data has been written to the screen. It is a good place to initialise local variables on the main form, and to disable edit fields and buttons before the user sees them.

CR: sel←⍬ ⋄ user←'unknown'
CR: ⍺ CPro.Do ('Disable' 'undo')('Check' 'checkme')

It is also a handy trick to capture the names of any commonly used controls as local variables on the form, so that you can easily run events on them later.


CPro Turorial and Reference: Destroy (DS)

Destroy (DS)

Run immediately prior to the object being erased from the workspace. Cannot be rejected!

DS:'Farewell cruel world'

... is about all you can do here!


CPro Turorial and Reference: Validation (VL)

Validation (VL)

This event is reported after data has been retrieved from the screen, but before it is assigned back to the attached APL variable. The expression you put on the behaviour table can either modify the data and pass it through, or reject the event, in which case no assignment is done, and the screen is restored to the previous value.

The working copy of the data may be accessed in the behaviour expression as ‘⍵‘ and treated just like any normal APL variable ...

    : ⍵←12⌊⍵        ⍝ Data cannot exceed 12
⍵≤0: : CPro.Reject ⍝ Reject if -ve

Note the use of CPro.Reject to signal rejection. In this case, the validation check is coded in the ‘Rule’ column of the Event-Action Table.


CPro Turorial and Reference: Post Creation (PC)

Post Creation (PC)

This is signalled by form and grid objects when they have been created and updated with data. It can be used on the main form to grey out or check required menu items.

⍺ #.CPro.Do ('Check' 'tickme')('Disable' 'greyme')

... where ‘tickme’ and ‘greyme’ are the ids given to these entries in the menu definition.


CPro Turorial and Reference: Post Update (PU)

Post Update (PU)

This is signalled by all objects when data has been successfully returned to the associated data variable. It might be used to trigger subsequent processes, for example a background update to a database.


CPro Turorial and Reference: Close Request (CL)

Close Request (CL)

This is signalled by the main form and the MDI child when the user attempts to close it, either with a <Close> button or from the system menu. It is a good place to check for unsaved data, and possibly cancel the request ...

CL: 2=Win.Ync 'Save changes?' : #.CPro.Reject

This puts up a standard ‘Yes/No/Cancel’ message box, and if 2 is returned, it does not exit. (This one doesn’t save the data either.)


CPro Turorial and Reference: Pre-refresh (PR)

Pre-refresh (PR)

Is signalled to all objects which have data (static or active) properties before each data expression is executed. The application may use this to condition the data in some way, or initialise the variables if they don’t already exist.

The data passed as the event argument is the list of variable names which triggered the event. This will be null on the first invocation, as all objects are refreshed immediately after creation.


CPro Turorial and Reference: Refresh Completed (RC)

Refresh Completed (RC)

This event may be handled in the normal behaviour table for the object. It is queued by Causeway when the properties of a control have been refreshed – the event message lists the properties which were refreshed in that call.


Reference: Technical Information

This section sweeps up all the miscellaneous technical details.

  • Object Styles
  • Identifying Objects
  • Attach to edges
  • Grid Specification
  • Using Object Hints
  • Accelerator Keys
  • Object Captions
  • Cue Cards
  • Charts (RainPro graphs)
  • Modal Dialogues
  • The Dialogue Box Format
  • The Style Table Format
  • The Domains Table Format
  • Customising the Error Text
  • Getting Help and Support
  • Tutorials
  • The Picture Editor


CPro Turorial and Reference: Object Styles

Object Styles

Styles allow you to make global changes to your dialogues without redrawing all the dialogue boxes individually. For example, all prompts pick up the ‘Prompt’ style automatically. By default this is set to ‘Blue’, but if you change the entry in the style table Class.∆styletab to be ('FCOL' 128 0 0) all your prompts will become red immediately.

When you use the ‘Appearance’ dialogue in the Designer, you are offered a choice of all the styles which are applicable to the object you are working on. Select as many as you want, e.g. to make an editor suitable for APL functions, choose ‘APLtext’ and ‘Editor’ as styles for a Notepad.

To align a field caption to the left of the field, set the style to ‘side’, which changes the placement and right-justifies the label text.

Adding Extra Styles

Class.∆styletab is a four-column table. Column-1 is a short tag for the style (please do not change this for the built-in styles); column-2 is a description of the style; column-3 is the (interpreter-specific) code which implements it; column-4 lists the object to which the style applies. You can add your own entries to this table. If they are applicable to all objects, leave column-4 empty; otherwise list the objects to which the style applies, and the Designer will only offer you the choice of acceptable styles in its ‘Appearance’ dialogue.

In the Class namespace you will find a rudimentary editor which applies a reversible format to the style table such that you can change it with the normal Dyalog editor, and then execute the result to regenerate the correct nested format:

ded '∆styletab'

Please use with care!


CPro Turorial and Reference: Identifying Objects

Identifying Objects

It is sometimes helpful to refer to a selection of objects by a family name, for example to set a whole group of buttons to ‘inactive’ at a single call. To do this, you give them all a ‘group’ name:

 'btns' ∇Do 'Disable'

You can put an object into several groups, so quite complex patterns of behaviour are possible here as #.CPro.Do will run the function on every object in the group if you pass a group name on the left.

If you really need to get at the true Dyalog name for some objects (maybe to set a property directly with ⎕WS) use #.CPro.Id 'groupname' to retrieve the true names which CPro assigned to the objects in the group when it created them. Note that this always returns a nested vector, even if there is only one object in the group.


CPro Turorial and Reference: Negative Geometry

Negative Geometry

All objects can have any combination of negative position and negative size.

Negative position is easy – it simply sticks the object to the opposite edge of the form. To stick a <Close> button to the lower right corner (so it stays there even when the user stretches the form) set its position to (¯12 ¯12) or some such.

To make a notepad stretch with the form, leave the position positive, and set the size to the sum of the borders in that dimension ... e.g. (16 16)(¯32 ¯32) will centre and stretch.

The anchor buttons in the designer basically do all the arithmetic for you, but it probably helps to understand what they are trying to do!


CPro Turorial and Reference: Attach to edges

Attach to edges

Causeway handles the Dyalog Attach mechanism by using the same approach as Motif – objects are gven negative positions or sizes which has the effect of positioning the ‘far side’ relative to the far side of the container.

See also ...

Negative Geometry


CPro Turorial and Reference: Local Variables on Forms

Local Variables on Forms

This is APL, after all! Forms behave just like monadic functions, i.e. they may take a list of arguments, maintain local variables, and return a list of results.

Locals are named by including them in the form’s “locals” property box. You can then use the ‘Create’ action on the form to assign default values, or to pick up passed arguments ...

('Adrian' 40) #.CPro.Call dbx.hi    ⍝ Pass name and age

   This is my Form (locals: nm age msg)
   CR: (nm age)←#.CPro.Args ⍵ ⋄ msg←'OK'  ⍝ Get args
   CR: sel←⍳0 ⋄ name←'(untitled)'       ⍝ Set up local vars

Similarly, you might set the ‘select’ action on your OK button to return the new value of age ...

∇Return age

This keeps the workspace much tidier, and makes it easy to program a safe exit on <Cancel> which must avoid changing global data. If you call a form with no arguments, #.CPro.Args returns a scalar zero, which is as safe as anything!

Note that you can pass arguments to #.CPro.Make, but it cannot return a result as it runs asynchronously.

Scoping Rules and Namespaces

Event tables on Causeway forms are implemented internally as functions, mainly to ensure that they behave in exactly the same way as conventional function calls with respect to localisation rules. For example if Form1 runs an action on a button to call Form2, then all the locals in Form1 remain visible to Form2, unless it has the same names localised. This remains true even if the application has used ⎕CS to change namespace, as local variables are carried across namespaces by the APL call stack.

This is not quite the same if you use ∇Make to create the child form. In this case you can still see locals on the parent form, but because you are no longer in a calling stack, these locals are not carried across ⎕CS in the same way. You can still locate them, but you will need to use ##.local whenever you refer to them from actions on the child form.

If for some reason you need to get at local data on a form which is not the parent of the current form, there is a CPro utility #.CPro.Execute which can do this for you.


CPro Turorial and Reference: How Menus are Handled

How Menus are Handled

Causeway does not treat menus, menu-items etc. as objects – instead the menu structure is treated as a property of the form. If you use Dbx to design the form, just name the menu definition as its menu property. Otherwise, you can use #.Class.AddMenu to attach a menu to forms you have made, or to make pop-up menus as a ‘Mouse-down‘ action.

#.Class.AddMenu ∆menutree   ⍝ adds a menu to 'FM1'

A typical menu structure (vector of text vectors) might be ...

[menubar]
 &File>File
 &Edit>Edit

[File]
 &New=Ctrl+N   :∆new_file  ⍝ Clean sheet
 &Save=Ctrl+S  :∆SAVE 0
 Save&As       :∆SAVE 1 :titlebar
 &Junk:⍳12::greyme
 --- separator ---
 E&xit:∇Return ⍬
[Edit]
 ..... and so on

The first section name is optional; you can call the rest by any valid APL name. The ordering of sections (after the first) is immaterial, and the menus are built recursively to whatever depth Windows allows!

The indenting and white space is also optional, but recommended! Notice the use of accelerator keys for New and Save; anything you put after the ‘=’ is automatically set up as an accelerator for that menu entry.

If you end the line with :varname:id as in the [File] example, selecting the Menuitem notifies a change to variable varname. The item identifier id can be used in commands to the parent form, so that you can set properties (enabled etc.) as needed:

  CR: fnm←⍺   ⍝ Catch the form name on creation
  fnm ∇Do 'Disable' 'greyme'   ⍝ Grey the menu option
  fnm ∇.Do ' Check' 'checkme'  ⍝ Check the menu option

If you want a ‘right-button’ pop-up, just use #.CPro.Menu with no left argument:

∇Menu 'One:2+2' 'Two:3+3' ⍝ Make a pop-up menu

Adding ‘Hints’ for your Menu Items

As well as the hot-key, you can continue the caption with ‘Hint’ text following a semi-colon, for example:

&New=Ctrl+N ; Starts a new File

This extra information will echo to your Status Bar as the user moves the mouse around the menu items.

Using Special Key Codes in Menus

You will have noticed that the symbols ‘=:;>’ are used as part of the syntax of the menu definition, and therefore cannot be included in either the caption or the hint text. It may also be useful to include the tab character to get the menu captions nicely aligned. The following characters may be used here:

... ^t ... Tab character
... ^e ... Equals Sign
... ^c ... Colon
... ^s ... SemiColon
... ^g ... Greater Than Sign

For example:

[File]
 &New=Ctrl+N;This wipes your data^c then it makes a new file:NEW
 &Save=Ctrl+S;Save early ^g^g save often!:SAVE

Presetting the ‘Checked’ and ‘Enabled’ State of Menus

You can define a menu item as ‘Checked’ by preceeding the caption with the ‘#’ character, and you can disable it with the ‘~’ character. This is particularly useful when calling popup menus, as you get no other opportunity to set these properties:

#.CPro.Menu 'One:1+1' '~Grey Two:2+2' '#Checked 3:3+3'

However this will also work correctly with normal menus on forms. You could use it to disable options which are intended for a future release but are not yet available to the user.

You can enable and disable menu items and entire sections on the fly with the Enable and Disable functions on the main form.

Using Radio Groups in Menus

You can have any collection of menu items (between a pair of separators) act as a radio group. Prefix the captions by either Jot or Circle – the item with the Circle (there should never be more than one in any group) will be shown on the menu with a solid circle. Use the Check function on the form to switch the blob to any of the other items in the group.

These prefixes will also work in popup menus built with CPro.Menu or Win.Popup, but of course there is no way the user can switch the radio marker and see the effect here!


CPro Turorial and Reference: Using Object Hints

Using Object Hints

All the standard Causeway objects may have an associated ‘Hint’ property which will be displayed in the status bar as the mouse passes over the object. For example you might caption an Action Button:

Caption:&Calc
Hint:Calculates new data

This will show ‘Calc’ on the button, and whenever the mouse passes over it you will see ‘Calculates new data’ displayed in the status bar across the bottom of the form. The same trick works in menus – just add the hint after a semi-colon in the menu caption.

Note that you must use a ‘ST’ object to make this work – Causeway does not yet offer the possibility of using other objects for hints (although you could always do this yourself with ⎕WS).


CPro Turorial and Reference: Accelerator Keys

Accelerator Keys

Skipping to Fields

Captions on all fields can be used to give fast access to the field with the cursor. If you use an & to mark a suitable mnemonic character, the user can skip immediately to the field with Alt+character.

Setting ‘Hot Keys’ for Objects

There are several common standards in Windows, for example many systems (such as PowerPoint) use Ctrl+S as a keyboard shortcut for ‘File, Save’. Unfortunately, not even Microsoft are consistent in their use of these, so it is probably as well not to overdo them.

Warning: if you require the APL keyboard in your application, and use a Unified keyboard, the hot keys get the first look at the keystroke. Setting Ctrl+S disables the ‘upstile’ character anywhere in the same form!

Causeway supports automatic accelerator keys for menu items (just add ‘=Shift+Ctrl+F2’ to the caption) but you can also add your own hot key to any object with a simple entry in the Event-Action Table for the object:

  : CR :   : ⍺ ∇Accel 'Ctrl+A'  :  :
  : SL :   : 'Hi there'            :  :

This logs ‘Ctrl+A’ as the hot key for the object. When the key combination is pressed it triggers a ‘Select’ for the object, and the line of code ‘Hi there’ will execute. Many common classes (such as the Action Button) have an ‘Accelerator’ property that does this for you.

Supported Keystrokes

The current Causeway release supports any combination of ‘Alt+Ctrl+Shift’ with any key from A-Z, the function keys F1-F12 and PgUp, PgDn, Home, End and many others. See CPro.∆ansi for the complete set – note that blanks are removed from your hot-key name before it is matched with this list, so ‘Page Down’ will correctly match an entry for ‘PAGEDOWN’.


CPro Turorial and Reference: Object Captions

Object Captions

In Causeway, all objects have a caption. This is fixed text, which is normally written above the object, left-aligned. It gets the ‘Prompt’ style automatically.

You can force the caption to right-align to the left of the object with style ‘side’ (useful for crowded forms with many edit fields).

Icon holders are the exception – they are captioned below, centred, in MS Sans Serif 10 to match the normal appearance of Program Manager icons.


CPro Turorial and Reference: Cue Cards

Cue Cards

Cue cards are small independent forms which you can make for any of the APL objects in the Designer. They simply display the object’s documentation where you can easily refer to it to check how it behaves and what data should be attached to it.

All the cue-cards have a <Help> button which takes you directly into the help file at the entry for the object in question.


CPro Turorial and Reference: Charts (RainPro graphs)

Charts (RainPro graphs)

Graphs from RainPro may be created (and shown) by the Chart class, or charts created programatically may be displayed (and modified in place) with the PS class.


CPro Turorial and Reference: Modal Dialogues

Modal Dialogues

The normal approach to building systems in Windows is to allow the user to interact with any object at any time. This could be called ‘non-modal’ behaviour.

If your program absolutely has to get some piece of information before it can continue, then you want the user ‘locked in’ to the dialogue which is requesting the information. For example to insert a bitmap into a help-file, it is pointless and potentially confusing to allow the user to change the underlying topic text until he has given you the name of the bitmap! Hence you will use a modal dialogue to request it:

  →(#.CPro.Call dbx_bmp)↓0    ⍝ Get bitmap to insert

Which conventionally returns 1 for <OK> and 0 for <Cancel>.


CPro Turorial and Reference: The Dialogue Box Format

The Dialogue Box Format

In CausewayPro, dialogue boxes are held as a 5-column matrix, of which the first row defines the form and the remaining rows define the controls. The columns give:

  1. The class mnemonic, typically two characters.
  2. The object caption.
  3. The position of the object in pixels (row,col) from the top left. Negative numbers measure from the opposite edge of the parent form to the opposite edge of the control.
  4. The size in pixels (height,width). Negative numbers give the margin remaining (top+bottom or left+right) outside the object. If the form is resized, the object will stretch to preserve these margins.
  5. Any remaining properties, listed as Property-Value pairs.

Some of the common elements in the 5th column are:

    A vector of styles for the object. These match the style mnemonics in the 1st column of Class.∆styletab (see below).

  • The reference variable for the object (this cannot be changed by the user).
  • The data variable. Generally this is changeable by the user.
  • The list of names to listen for. This is a two-column matrix: the first column is the names; the second is zero or 1 to switch partial or full refresh of the object when that variable changes.
  • The event-condition-action table for the object. This is a four-column matrix giving the event mnemonic, an optional condition, the action, and the list of variables to holler.
  • The Group name(s) of the object. Several objects may share the same group, in which case they will all be reported by the #.CPro.Id function. Similarly, an object may belong to several groups.


CPro Turorial and Reference: The Style Table Format

The Style Table Format

The style table #.Class.∆styletab holds a variety of miscellaneous object properties. It will be much reduced in future versions of Causeway with many entries replaced by class-specific properties. The format is:

  1. Style mnemonic.
  2. Style description. These are the entries shown in the Appearance dialogue of the designer.
  3. Dyalog (property,value) pairs required to implement the style. These are catenated to the basic object definition before it is passed to ⎕WC for execution.
  4. List of classes to which the style should be applied. If this list is empty, the style is universal.

You may modify existing styles or add new entries to this table. Please do not delete entries without careful testing as some Causeway functions (such as #.CPro.Init) rely on certain styles being present.

Warning! If you have modified this table and wish to upgrade Causeway, make sure that you copy your modified version to a dummy variable before you copy in the new Causeway Class namespace. A good strategy is to keep your styles in a separate variable and catenate this to the top of Class.∆styletab after each upgrade.


CPro Turorial and Reference: The Domains Table Format

The Domains Table Format

This table is used to control cell formatting in the grid (text matrix and numeric matrix objects). Again, you may modify entries, but a better strategy is to modify your own table and catenate this to the top of the standard Causeway-supplied table after each upgrade. That way you effectively over-ride any Causeway domains of the same name. The structure of the table is:

  1. The Domain mnemonic. The text matrix defaults to TX domains and the simple numeric matrix to NM.
  2. A short description. This is currently unused by Causeway.
  3. The Dyalog arguments required to create a floating field of the required type. This is passed diectly to ⎕WC for execution.
  4. The value to be used in a new cell of this type (when the user adds a new row to the grid).
  5. The default column width for the domain. The last column of the grid will take up any slack width in the control. You can change this with the WideCols function on the TM class to nominate your own soakaway columns.
  6. The required value for the Dyalog ShowInput property.

You may like to use the supplied edit utility ded to help you edit this ...

ded '∆domain'

Please use with care as this does no validation whatsoever.


CPro Turorial and Reference: Customising the Error Text

Customising the Error Text

Causeway offers the option of a simple ‘recoverable’ error trap which shows an analysis of the error, and gives the user the option of aborting the application, retrying the problem action, or skipping past the problem. A typical error dialogue looks like:

This was generated from the default error text, which looks like:

Application Error
Error caused by: {ctl}
Error type: {type}
Problem code: {detail}
Please report the problem to support@causeway.co.uk

You may customise this by assigning your own text variable (a simple text vector delimited by ‘pipe’ characters) to #.CPro.∆errortext in your initialisation code.

The placeholders are used to report:

  • {ctl} is the type and caption of the control which caused the error, typically ‘Button <Press Here>‘ or the name of the form in the case of a menu action
  • {type} is the error type, typically ‘LENGTH ERROR’, as reported by APL
  • {detail} is the second element of the APL error message, giving the function-line which failed and the start of the source code. Very long lines are trimmed and the characters ‘gets’,’delta’ and ‘quad’ are shown as ‘=$#’ to aid readability in the messagebox.

You may omit any of the placeholders to simplify the reported error.


CPro Turorial and Reference: Getting Help and Support

Getting Help and Support

If you find a bug, particularly in the ∆core∇ Causeway functions we would very much like to know about it. Bugs in class code are generally easier to find and fix, but please report them anyway. It often happens that a new Dyalog release will add some features (for example multi-line headings on the grid) which will invalidate an existing class function. We rely on our users to tell us about these, as there is no way we can check all behaviours in the time available. You can help us by isolating the bug and making a simple workspace containing a function that demonstrates exactly where it occurs. Then you can contact us by:

  • email (preferred) on: causeway@compuserve.com. Send a short message first, then if necessary zip and mime the problem workspace and send it to us.
  • fax. Fax the problem report with as much detail as you can to +44 (0) 1653 697719 and we shall do our best to respond.


CPro Turorial and Reference: Tutorials

Tutorials

All the code and dialogues used by the tutorials are in the Tutor namespace in CProQA.

  • How to Design a ‘Main’ Application
  • Writing the Application Code
  • Adding Menus and Toolbars
  • Putting in ‘Proper’ Windows File Behaviour
  • Calling a Subsidiary Dialogue (Using a Grid)
  • Linking to a Help File
  • Running it for Real
  • Gaining Speed and Saving Disk Space
  • Running Causeway from QuadSE

Are the topics to work through.


CPro Turorial and Reference: The Picture Editor

The Picture Editor

The Picture Editor is a handy namespace for maintaining strips of bitmaps for attaching to toolbars or for use in creating imagelists.

It was written by Richard Smith, following a design by Duncan Pearson.


CPro Turorial and Reference: Event Reference

Event Reference

This section lists all the events which are reported by the various classes. These are generally passed through directly from Dyalog, so please refer to the Dyalog documentation for more information.

  • Mouse Down (MD)
  • Mouse Up (MU)
  • Mouse Moved (MM)
  • Double Click (DC)
  • Item Double Click (IDC)
  • Drag Drop (DD)
  • Key Pressed (KP)
  • Configure (CF)
  • Exposed (EX)
  • System Close (SC)
  • Iconified (IC)
  • Changed Data Event (CD)
  • Scrolled (SR)
  • Got Focus (GF)
  • Lost Focus (LF)
  • DDE Change (DE)
  • Timer Event (TI)
  • Help Request (HR)
  • User Defined (US)
  • Created (CR)
  • Destroy (DS)
  • Validation (VL)
  • Post Creation (PC)
  • Post Update (PU)
  • Close Request (CL)
  • Pre-refresh (PR)
  • Refresh Completed (RC)


CPro Turorial and Reference: CPro Function Reference

CPro Function Reference

This section lists all the public functions in the CPro namespace. Only 5 or 6 of these are required in the majority of typical applications.

  • #.CPro.Accel
  • #.CPro.Append
  • #.CPro.Args
  • #.CPro.Build
  • #.CPro.Call
  • #.CPro.Clear
  • #.CPro.Do
  • #.CPro.Execute
  • #.CPro.Form
  • #.CPro.Forms
  • #.CPro.GetContext
  • #.CPro.Id
  • #.CPro.Init
  • #.CPro.It
  • #.CPro.IsAccelFree
  • #.CPro.ListAccelerators fm
  • #.CPro.Make
  • #.CPro.MakeAsleep
  • #.CPro.Menu
  • #.CPro.Notify
  • #.CPro.Parent
  • #.CPro.Parse
  • #.CPro.Post
  • #.CPro.Qna
  • #.CPro.ReadNow
  • #.CPro.Recall
  • #.CPro.Reject
  • #.CPro.Reset
  • #.CPro.Return
  • #.CPro.SetClassPath
  • #.CPro.SetFocusTo
  • #.CPro.Sleep
  • #.CPro.UpdateAllChildren
  • #.CPro.Wait
  • #.CPro.Wake
  • #.CPro.Zap


CPro Turorial and Reference: From First Principles

From First Principles

Causeway is a Gui development environment which lets you build reliable APL Gui applications faster than any other tool you can buy. This manual combines the tutorial and reference which were included with previous versions of the software.

Howto
How to Use this Tutorial
Intro
What is Causeway?
Visualising
Visualising APL Variables as GUI Objects
Events
Programming with Events

This release requires Dyalog APL 12 or above (Unicode or Classic edition). See Installation for details on what you need to include in your application workspace.

The CPro workspace is the property of Dyalog Ltd.


CPro Turorial and Reference: The CPro Class Library

The CPro Class Library

All the Gui classes supported by CPro are listed. You can easily build classes of your own, probably basing your work on one of these.

  • Action Button (AC)
  • Auto-filled Number (AFN)
  • Auto-filled Text (AFT)
  • Text Annotation (AN)
  • APL Text entry (APLTX)
  • Arc (captioned links) (ARC)
  • Backcloth (BK)
  • Bitmap Holder (BM)
  • Calendar (CAL)
  • Combo selector (CB)
  • Chart (RainPro graph) (CH)
  • Check Box Group (CK)
  • Close Button (CL)
  • Digital Counter (CT)
  • Drop-edit Combo (DC)
  • Date Entry (DT)
  • OK Button (EN)
  • Parent Form (FM)
  • Grooved Rectangle (GV)
  • Hidden Field (HD)
  • Time of Day (HM)
  • Help Button (HP)
  • Horizontal Splitter (HSB)
  • Horizontal Separator (HSEP)
  • Icon Holder (IC)
  • Image List (IL)
  • Label (LB)
  • Hyperlink (LBJ)
  • List Box (LS)
  • ListView (LV)
  • Numeric Matrix (MA)
  • MDI Child Form (MDI)
  • Most Recently Used (MRU)
  • Numeric Field (NM)
  • New-Open-Save-Exit (NOSE)
  • Notepad (NP)
  • Numeric Vector (NV)
  • Parameter Bar (PA)
  • Picture Button (PB)
  • Progress Indicator (PI)
  • Plinth or Recess (PL)
  • Poly Marker (PM)
  • PostScript Graphics (PS)
  • Polyline (PY)
  • Cancel Button (QT)
  • Radio Button Group (RB)
  • Containing Region (RGN)
  • RTF Editor (RTF)
  • Floating Palette (RU)
  • Status Area (Parent Region) (SA)
  • Scroll Bar (SB)
  • Status Field (SF)
  • Drop-down Selection (SL)
  • Spin Box (SP)
  • Status Bar (ST)
  • Subform (SUB)
  • Systray Item (SYS)
  • File Tabs (TAB)
  • Toolbar (TB)
  • Tool Control (TCTL)
  • Timer (TI)
  • Track Bar (TKB)
  • Tool Button (TL)
  • Text Matrix (Grid) (TM)
  • Tool Button – new style (TO)
  • TreeView (TR)
  • Tabbed Subform (TSF)
  • Text entry (TX)
  • VCR Buttons (VC)
  • Vertical Splitter (VSB)
  • Vertical Separator (VSEP)
  • Web Browser (WB)
  • Yes/No choice (YN)