Crunch CRiSP File Editor 6 - Manual (Page 55)

Page 55
it. At various times you need to refer to the individual objects within the dialog box, e.g. so that you can
retrieve the current status of the object, change an attribute value, or decide in the callback code, which
object has just been actioned on by the user. In order to do this, you need to give an object a name (via the
DBOX_NAME attribute). It is not mandatory that you do give an object a name, but you will not be able to
refer to the object without one. (You might create DBOX_SPACER objects in a dialog box to control the
spacing between user visible objects, but a DBOX_SPACER object has no semantics so there is little point
in giving an object a name).
A name is an arbitrary string used as an argument to the DBOX_NAME attribute. There are no particular
restrictions on the syntax of the name, but it is useful to something meaningful. Every object inside a dialog
box should have a unique name or no name. If two or more objects have the same name, then it is
indeterminate as to which one will be accessed when you refer to an object in your macro code.
Different dialog boxes can contain objects with the same names as objects in other dialog boxes. Effectively
the name of an object within a dialog box can be considered to be of the form: <obj_id>.<name_id>, where
<obj_id> is the return value from the create_object() primitive, and the <name_id> is the value of the
DBOX_NAME attribute.
Remember that CRUNCH supports switch statements using string expressions. If you look at the supplied
CRiSP macros you will find that switch statements are used in many of the dialog box handling macros to
distinguish the object that caused the callback to occur.
Creating a Dialog Box
A dialog box is created via the create_object() primitive. The create_object() primitive takes a single
argument, which is a list describing the dialog box. This may sound simple, but real dialog box descriptions
can extend over hundreds of lines.
The first thing is to break down the description of a dialog box into its components: push-buttons, input
fields, etc. CRiSP supports a number of user interface components.
Before progressing any further, let us show a very simple dialog box description:
int obj_id;
obj_id = create_object(make_list(
DBOX_TITLE, "Title at the top of the dialog",
DBOX_CALLBACK, "callback_function",
DBOX_LABEL, "This is some text in the dialog box",
DBOX_BUTTON, " Ok ",
DBOX_DEFAULT_BUTTON
));
This dialog box is extremely trivial but illustrates a number of basic areas of the dialog box creation
mechanism.
The first thing to notice is the declaration of an integer variable, obj_id. When a dialog box is created, an
object identifier is returned which allows the dialog box to subsequently be referred to, e.g. for the purposes
of inquiring about attribute values, or for changing attribute values.
The next thing to notice is the use of the make_list() primitive which is used to create a list argument which
is passed to create_object(). Remember that create_object() takes a single argument. The reason for this, is
that a dialog box can be conditionally constructed by creating a list, and then calling create_object() with that
list parameter. If create_object() took multiple arguments, then it would be very difficult to support conditional
arguments. (The C language does not support conditional function arguments either). The actual list
argument contains elements which are integers, strings or nested lists of arbitrary complexity.
When a dialog box is created, you can picture the argument list definition like this:
attributes of the dialog box itself
object-1
attributes for object-1