MetaCard Corporation

FREQUENTLY ASKED QUESTIONS

22. Can I call 'C' functions from MetaCard?

On UNIX systems, the file external.tar.Z in the standard distribution has templates for doing this. These same templates are placed in the Externals folder in the Win32 and MacOS distributions. MetaCard can call commands and functions in the external, and these external 'C' routines can call back to the MetaCard engine to get and set variables and to execute commands.

See the MetaCard Tutorials stacks for a demonstration of the external capability and instructions on how to create and modify externals.

23. What is embedded MetaCard (libmc.a)?

The MetaCard distribution comes with a template for calling C functions and a tutorial that explains how to use it. On UNIX systems, this standard system spawns the external C functions as a separate process and uses X properties to pass information between this external and the MetaCard engine. It is suitable for most applications that need to call C functions to access databases or specialized libraries. Due to the communication overhead, it probably isn't suitable for applications that need to call C functions repeatedly in loops. It can also be difficult to debug externals since they're run as separate processes, and so developing large externals can be very time consuming.

To remove these limitations the MetaCard engine is also available in an embedded version on UNIX systems. This library (libmc.a) can be linked directly to applications which can call MetaCard functions with only normal function call overhead (which can be up to 40 times faster than communicating via properties), and which can be debugged using ordinary debugging tools.

On Win32 systems, externals are built as DLLs. Since debugging DLLs is relatively straightforward, and since performance isn't a problem with this architecture, Embedded MetaCard is not available for Win32 systems. For MacOS, externals are stored as code resources, which also are relatively easy to debug and don't have major performance penalties associated with them.

24. How do I communicate with MetaCard from my Motif application?

The XT program in the external.tar.Z file is an example of this, and can be used as a template for using MetaCard as a help system for your Motif application.

25. What printing support is provided?

MetaCard 2.0 supports production of PostScript files of cards images on UNIX systems. These files can be printed on most PostScript printers. The standard system printing features available on Windows 95/NT and MacOS are accessible from the MetaCard engine for those platforms.

You must use the "Print Setup" dialog to set the printing parameters before printing cards. See the help for that dialog and the card describing the print command in the MetaTalk Reference for more information on printing.

26. Does MetaCard support 2D or 3D graphics?

2-d vector (object) graphic capabilities similar to what is available in SuperCard and ToolBook are included in MetaCard. The property names are the same as those used in SuperCard where possible. For example, you can set the points property of a polygon style graphic to dynamically change the way it looks. See the demo stacks for examples using the graphic object.

You can also import EPS graphics on systems that support the DPS X server extension (RS/6000, SPARCSVR4, Alpha).

No support for 3D graphics is provided, but can easily be added using externals. See the external tutorial in the MetaCard Tutorials stack for and example of how to draw into MetaCard windows from external C functions.

27. Does MetaCard have a script debugger?

As of MetaCard 2.0, a complete GUI debugger and profiler is included with the MetaCard development environment.

Other common debugging techniques include using the put command to put things into the Message Box (equivalent to using printf with 'C' programs), using "write <expression> to stdout" to trace scripts by writing to the terminal window that MetaCard was started from, and using the "watch" command to watch variables. For more complex programming tasks, the external command interface can be used to produce C or C++ back ends to MetaCard user-interfaces.

28. Can I use MetaCard as a database?

The multiple card metaphor combined with full text search makes MetaCard an ideal platform for building small databases that contain unstructured information. Large databases (more than 1000 records) or those that require multiuser protection would best be implemented via external commands and a standard database package.

29. What are the system requirements for running MetaCard?

MetaCard takes less memory than just about any other UNIX GUI development system, especially anything based on the UNIX/X11 Xt/Motif toolkit (MetaCard is a C++ application built on a C++ graphical toolkit). It performs adequately on 8 MB CISC systems. On RISC systems, 12-16 MB RAM is recommended. Disk space requirements are also small: the entire distribution requires less than 5MB, the largest piece of which is the demo stack (which is not required for development).

30. How do I play audio/video in MetaCard?

MetaCard supports audio on systems with built-in support and on some systems with optional support. The recommended format for cross-platform use is 8-bit 8 kHz mulaw (the Sun/NeXT native format, also known as ".au") as this is the only format supported on all platforms. Higher quality formats such as AIFF and WAV are supported on Windows and Mac systems, but not on most UNIX platforms. The "play" command plays audio from a file or from an audioClip that has been imported into a stack.

The Windows 95/NT engine can play AVI files using Video For Windows as well as any format supported by QuickTime 3.0 (and later) if QuickTime is installed on the target system. The MacOS engine requires QuickTime 3.0 or later to play movies. The UNIX engines can play QuickTime, AVI, MPEG, and FLI/FLC animations, but only a limited set of QuickTime codecs is supported (specifically, Sorenson is not supported, nor is QTVR). The files can either be played directly from disk, or imported into MetaCard stacks before playing to reduce startup times on systems with sufficient memory. MetaCard has properties for scaling the movies, playing them back at particular locations within a window, changing their frame rate, and leaving the last frame of a movie on the screen (which can be used to make transitions between movies smoother). See the documentation for the "play" command and "player" object for more information.

There are several commercial video/movie players available, all of which can be made to work with MetaCard. MetaCard has properties and commands that allow starting and stopping these players, playing the movie into a MetaCard window, and sharing colormaps between the players and the MetaCard engine. The Win32 engine has an mciSendString command that can be used to send any command to any MCI-compatible device.

31. What are substacks and how should I use them?

During development, it's usually best to keep each stack in its own file as this eases making backups of stacks and opening the backups after having loaded a newer version. When you are nearing the release the application you're developing, choose one stack to be your main stack and use "Main Stack" dialog (from the "Stack Properties" dialog) to make some or all of the other stacks substacks of that stack. Which stack to choose as the main stack depends on the project, but it's often convenient to make it a license splash screen that comes up when the application is run and then closes itself and opens some other stack.

Remember that all messages sent to any of the substacks pass through the main stack. This means you have to be careful to check the target if you have any handlers for any of the standard MetaCard messages. This feature does make main stack scripts a good place to put handlers that are used in several of the other stacks in your application.

32. Which stack is "this stack"?

Many MetaCard dialogs (notably the Message Box and the menus) set the defaultStack property to the topStack before executing their scripts. The defaultStack property determines which stack is used when the chunk expression "this stack" is used (or the stack expression is omitted entirely) in a script.

The topStack is the top-most editable stack. It will usually have a page number in parentheses and may also have a "*" (denoting that the cantModify property is set to false) in its title bar. To avoid confusion, it is recommended that only a single stack be edited at a time. Close or iconize/minimize/collapse the others.

33. How do I get back to the stack I was editing?

To reopen a stack you have closed (which normally will be neither saved nor deleted when you close it), you can type the following into the Message Box where "my stack" is the name of your stack:
 topLevel "my stack" 
If your stack is saved as a substack of another stack, you can also open it from the Components dialog from the Stack Properties dialog of your mainStack.

If this stack will be used frequently, add a button to the Home stack with the "topLevel" command in a mouseUp handler.

34. How do I save a stack into its own file?

Use the "Save As..." item in the File menu and choose "Yes" if a dialog asking you if you want to make the stack a main stack appears.

35. How do I open a stack in the same place as another stack?

You can't, at least not reliably. The major problem is that window managers such as mwm aren't required to honor an applications request for window placement. Even if it does, when you specify a position for a window, it may be offset by the width of the window borders, which vary in size depending on which window manager is being used: use a different window manager, get a different position.

It is a much better design to use multiple cards for your application rather than trying to outsmart the window manager by positioning a stack by setting its loc or topLeft properties in a script. Also see the "in the window" option to the go command.

36. How do I run other programs from a script?

Use the shell() function or the "open process" command. See the MetaTalk Reference and Concepts & Techniques stacks for details.

37. How do I use MetaCard to build non-graphical programs?

Any UNIX MetaCard engine can be used execute scripts stored in text files instead of in stacks (this feature is not available on Win32 or MacOS engines). By convention, these script files should have a ".mt" extension. The script is executed by making it the first command line parameter (e.g., "mc sample.mt").

The scripts should contain an "on startUp" handler, which will be called when the script is executed. The script can read from its standard input with the statement "read from stdin until empty", and can write to its standard output with "write x to stdout". The "put" command without a destination container will also write the expression to stdout (normally it goes into the Message Box in this case).

38. How do I import images?

Use the "Importer" dialog box (from the File menu). MetaCard can import GIF, JPEG, BMP, XPM, XBM, XWD, and all PBMplus image formats. See the "import" and "export" commands in the MetaTalk Reference stack for details.

The easiest way to import images in MetaCard is to use the snapshot feature: open the image using the application used to create it or an image viewer application, and then import a snapshot of it with the "import snapshot" command or the "Importer" dialog.

The PBMplus image conversion package is a freeware package that will convert most common image formats on UNIX systems. It can be acquired from many Internet archive sites. It is also available on many CDs including the UNIX Power Tools book/CD (O'Reilly & Associates/Bantam Book ISBN 0-553-35402-7) and most Linux CDs.

If you want or need a commercial image conversion product, Image Alchemy from Handmade Software may do the trick. If you need to convert images produced on a Macintosh, DeBabelizer from Equilibrium may be a better solution.

To avoid running out of colors, in which case MetaCard does a simple nearest-color remapping of the image, consider quantizing the images to reduce the number of colors they use. Remapping all of the images to use the same colormap is also a good way to reduce the number of colors required. A good rule of thumb is to use no more than a total of 160 colors for all of the objects in a stack.

39. How do I put an image into a button (icon)?

Any image can be used as an icon, though transparent GIF is the format most appropriate for them . The most common technique is to import all of the images that will be used as icons and fill patterns in that stack onto a single card of your stack. This card won't ever be seen by the users of the stack and so its appearance isn't critical.

On UNIX systems you can import non-transparent images and edit them to make them transparent. To do this, choose the bucket tool from the Paint Tools palette and click mouse button 2 in the background. This will will erase all connected areas of the same color.

Next, double click on the image with the pointer tool and write down the id of the image. Go to the card where you want the button to be and create a button. Make sure the button is selected and then set the icon property to the id of the image (1234 in this example) using the Message Box:

set the icon of the selectedObject to 1234

The same technique can be used to set the backPattern property of a button or any other type of object.

40. How do I create text that uses 16 bit or ISO 8859 characters?

To access high bit characters (upper 128 characters in an 8 bit font) on UNIX/X11 systems, you can use the mod3 key to toggle MetaCard fields to enter characters with the high bit set. Use the program "xmodmap" to determine which keyboard key is bound to to mod3 and to bind one if there isn't one already. Unfortunately, learning the key binding can be difficult.

If you only have a few characters to enter, the easiest way is probably using the "Character Chooser" or the numToChar() function (on UNIX/X11 systems, you can get the number of the character you need by displaying the font with the "xfd" program).

To access the fonts for other languages (e.g. those that use 16 bit characters), you'll need to set the textFont property to the font name in the "Object Font" dialog, or by typing it into the Message Box. To specify a font set on UNIX systems (for 16-bit fonts), put all of the fonts required (separated by commas) in the textFont property.

For example, to make the first line of a field be displayed in the Kanji24 font, you'd type: set the textFont of line 1 of field "some field" to "kanji24". Use the X program "xlsfonts" to find out which fonts have been installed on your system. Note that isn't possible to edit 16 bit text, you can only import it from a file produced in another editor, or by using "quick paste" (select the text in editor window and click mouse button 2 in the MetaCard field where you want to paste the text).

Support for Unicode and other 16 bit character sets is not available in the Win32 or MacOS engines yet.

41. Why is there more than 1 background?

To provide maximum flexibility in control and script placement, a card can have zero or more backgrounds. All messages sent to the card (and controls on the card) are passed through each of the groups on that card.

Without a background, everything goes on the card layer. Multiple backgrounds can be created and the "Edit Backgrounds" dialog box can be used to place them on or remove them from cards.

Note that "groups" and "backgrounds" are the same thing. The only difference in the use of the terms is that when addressing objects, "groups" are accessed relative to the card and "backgrounds" are accessed relative to the stack, so group 2 is the second group on the current card, whereas background 2 is the second group in the stack, and may not even be used on the current card.

42. How do I edit the standard dialogs and menus?

Any of the supplied dialogs can be edited by bringing up the dialog in topLevel mode (type 'topLevel "Stack Name"' into the Message Box). You may also have to unset the cantModify property (in the Stack Properties dialog).

To save any changes you make, be sure to save the tools stack, since these dialogs are not part of the Home stack (type 'save stack "MetaCard Menu Bar"' into the Message Box to save the tools stack. Note that the file mctools.mc must be writable for this to work).

43. How do I build menus? How about combo boxes?

There are four ways to implement menus, combo boxes and other "multiple choice" controls. The easiest way is to set the style of the button to the appropriate value and to enter the strings that will be displayed in the menu into the "Contents" field in the "Properties" palette. When the user chooses one of the items in the menu, a menuPick message will be sent to the button with the name of the menu choice as an argument.

The second way is to set the "menuName" property of the button to a stack name (any stack can be used as a menu panel). See the MetaTalk Reference stack for details on this command and property. The "Menu Properties", accessible from the "Button Properties" palette supports setting many menu-related properties. Note that the easiest way to build these menu stacks is to clone the existing menus. See the Concepts & Techniques stacks for tips on how to do this.

The third way is to simulate a menu panel using a field (or group) that you hide and show. Finally, you can use the "popup" command to open a menu panel over any control.

44. Where is the menu separator control?

There is no menu separator control, separators are really 4 pixel tall buttons with their autoArm properties set to false. The "Lay Out Menu" button in the Utilities stack will size buttons into separators if their initial size is below a certain threshold.

If the first character in a line in the button contents is a - character, the menu created by that button will have a dividing line at that point.

FAQ | Overview . Licensing . How To . Common Problems . Consultants . Testimonials