cdesktopenv/cde/doc/C/guides/builderGuide/ch05.sgm

<!-- $XConsortium: ch05.sgm /main/7 1996/09/08 19:48:26 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="ABUG.crobj.div.1">
<title id="ABUG.crobj.mkr.1">Creating and Editing Panes, Menus, and Messages</title>
<para>Most App Builder objects are dragged from the windows, panes, or controls
palettes. Some objects (layered panes, paned windows, menus, and messages)
are <emphasis>created</emphasis> objects. This chapter explains how to create,
use, and edit these objects.</para>
<informaltable id="ABUG.crobj.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating and Editing Pane Entities40'--><xref
role="JumpText" linkend="ABUG.crobj.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Layered Panes41'--><xref role="JumpText"
linkend="ABUG.crobj.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Paned Windows42'--><xref role="JumpText"
linkend="ABUG.crobj.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating and Editing Menus45'--><xref
role="JumpText" linkend="ABUG.crobj.mkr.11"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Menu Property Editor45'--><xref role="JumpText"
linkend="ABUG.crobj.mkr.12"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating and Editing Messages56'--><xref
role="JumpText" linkend="ABUG.crobj.mkr.19"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Message Editor56'--><xref role="JumpText"
linkend="ABUG.crobj.mkr.20"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Example: Writing Code for Messages61'--><xref
role="JumpText" linkend="ABUG.crobj.mkr.25"></para></entry></row></tbody>
</tgroup></informaltable>
<sect1 id="ABUG.crobj.div.2">
<title id="ABUG.crobj.mkr.2">Creating and Editing Pane Entities</title>
<para>There are four types of pane objects on the Panes palette of the App
Builder primary window: control pane, text pane, draw area pane, and term
pane. In addition, there are three types of <emphasis>created</emphasis>
pane entities: child panes, layered panes, and paned windows.</para>
<sect2 id="ABUG.crobj.div.3">
<title>Child Panes</title>
<para>A <emphasis>child pane</emphasis> is a text pane, term pane, or draw
area pane that has been dropped on a control pane and made a &ldquo;child&rdquo;
of the control pane. In App Builder, for example, the Label field in the
Label Property Editor is a text pane that is a child of a control pane.<indexterm><primary>child pane</primary></indexterm>
</para>
</sect2>
<sect2 id="ABUG.crobj.div.4" role="Procedure">
<title id="ABUG.crobj.mkr.3">To Create a Child Pane<indexterm><primary>childpane</primary></indexterm><indexterm><primary>creating</primary><secondary>child pane</secondary></indexterm></title>
<orderedlist><listitem><para>Drop a text pane, draw area pane, or term pane
on a control pane in the interface.</para>
<para>A message dialog box will be displayed, asking if you want to create
the dropped pane as a child of the control pane or as a layered pane.</para>
<para>Click Cancel if you do not want to create a child pane or a layered
pane.</para>
</listitem><listitem><para>Click Child.</para>
<para>The pane will be instantiated at the drop location, just as if it were
a control object. The pane will be a sibling of the control objects on the
control pane. You will be able to select the pane and move it around on the
control pane just like any other control object.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.5">
<title id="ABUG.crobj.mkr.4">Layered Panes</title>
<para>A <emphasis>layered pane</emphasis> is a &ldquo;stack&rdquo;
of two or more panes, one on top of the other. In App Builder, for example,
the Revolving Property Editor, which is used to display the properties of
each of the interface objects, is a layered pane.<indexterm><primary>layered panes</primary><secondary>definition of</secondary></indexterm>
</para>
</sect2>
<sect2 id="ABUG.crobj.div.6" role="Procedure">
<title id="ABUG.crobj.mkr.5">To Create a Layered Pane<indexterm><primary>layered panes</primary><secondary>creating</secondary></indexterm><indexterm><primary>creating</primary><secondary>layered panes</secondary></indexterm></title>
<orderedlist><listitem><para>Drop a pane on another pane in the interface.
</para>
<para>A message dialog box will be displayed, giving you the option to create
a layered pane.</para>
<para>If you have dropped a text pane, draw area pane, or term pane on a control
pane, you will also have the option to create the object as a child of the
control pane.</para>
<para>Click Cancel if you do not want to create a child pane or a layered
pane.</para>
</listitem><listitem><para>Click Layer.</para>
<para>The pane will be instantiated as a layered pane on top of the pane it
was dropped on. Because it is the same size as the original pane, it will
obscure the original pane completely. If you resize one of the layers of
a layered pane, all panes are resized. See <!--Original XRef content: '&xd2;To
View Layered Panes'--><xref role="SectionTitle" linkend="ABUG.crobj.mkr.6">
for instructions for viewing the layers of a layered pane.</para>
<para>Once you have completed the interface you may want to change the Size
Policy of any panes in a layered pane to Fit Contents (the default value
is Fixed, which should be retained until the interface is complete). Each
of the panes might be a different size.</para>
</listitem></orderedlist>
<note>
<para>There is no direct way to <emphasis>unmake</emphasis> a layered pane,
but you can accomplish the task by selecting one of the layers and choosing
Cut from the Edit menu of the App Builder primary window or from one of the
pop-up menus (displayed by pressing mouse button 3 in the interface or in
the Module Browser).</para>
<para>If you want to save the layer you cut, select an
empty window and choose Paste from the Edit menu. Repeat the Cut and Paste
process until there are no more layers (this is easiest to see in the Browser).
If you don't want to save the layers, choose Delete instead of Cut.<indexterm><primary>layered panes</primary><secondary>unmaking</secondary></indexterm><indexterm><primary>unmaking</primary><secondary>layered panes</secondary></indexterm>
</para>
</note>
</sect2>
<sect2 id="abug.crobj.div.7" role="Procedure">
<title id="abug.crobj.mkr.6">To View Layered Panes<indexterm><primary>layered panes</primary><secondary>viewing</secondary></indexterm><indexterm><primary>viewing layered panes</primary></indexterm><indexterm><primary>displaying</primary><secondary>layered panes</secondary></indexterm><indexterm><primary>layered panes</primary><secondary>displaying</secondary></indexterm></title>
<para>Only one layer of a layered pane is visible. To view other layered panes:
</para>
<orderedlist><listitem><para>Select the visible pane of the layered panes
in the interface or in the Module Browser.</para>
<note>
<para>Selecting a layered pane in the Browser does not pop the selected pane
to the top of the stack of panes in the interface.</para>
</note>
</listitem>
<listitem><para>Choose NextLayer from the View menu of the primary
window or from the interface pop-up menu (displayed by pressing mouse button
3).</para>
<para>The layer immediately beneath the current pane will be displayed. Repeat
this step to view other layers.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.8">
<title id="ABUG.crobj.mkr.7">Paned Windows</title>
<para><indexterm><primary>paned windows</primary><secondary>definition of</secondary></indexterm>A <emphasis>paned window</emphasis> is a combination
of two or more panes (control, text, draw area, or term panes, in any combination)
into one virtual window with multiple panes, one above the other, separated
by a movable sash. While the paned window maintains a constant height, the
individual panes become smaller or larger as you move the sash between them.
</para>
<graphic id="ABUG.crobj.igrph.1" entityref="ABUG.crobj.fig.1"></graphic>
<para>A paned window's initial size and position are determined by the position
and size of its panes: the left margin of the paned window is determined
by the left (West) edge of the pane that is furthest to the left. The width
of the paned window is determined by the width of its widest pane.</para>
<para>You can set limits on the minimum and maximum heights of any of the
panes by setting Pane Height in the Paned Window property editor. See <!--Original
XRef content: 'Appendix&numsp;B,
&xd2;Revolving Property Editor'--><xref role="AppendixNumAndTitle" linkend="ABUG.apRPE.mkr.1">,
for more details.</para>
<para>Once you have created a paned window you can resize the panes by pressing
mouse button 1 or mouse button 2 on the sash and moving it up or down.</para>
</sect2>
<sect2 id="ABUG.crobj.div.9" role="Procedure">
<title id="ABUG.crobj.mkr.8">To Create a Paned Window<indexterm><primary>paned windows</primary><secondary>creating</secondary></indexterm><indexterm><primary>creating</primary><secondary>paned windows</secondary></indexterm></title>
<orderedlist><listitem><para>Drag a pane from the Panes palette and drop it
on a main window or a custom dialog.</para>
<para>If you want the paned window to span the top of the parent window, drop
the pane on the top-left corner of the parent. The pane will be attached
to the window at its left and top margins with an offset of 0.</para>
</listitem><listitem><para>Resize the pane, if necessary.</para>
<para>If you want the paned window to span its parent window, drag the right
edge of the pane beyond the right edge of the window. The pane will be attached
to this edge, also.</para>
</listitem><listitem><para>Drag one or more additional panes to the main window
or dialog and drop them on an unoccupied portion of the window.</para>
</listitem><listitem><para>Select all panes that you want to be part of the
paned window.</para>
<para>Use mouse button 1 to select one pane and mouse button 2 to select
additional panes.</para>
</listitem><listitem><para>Choose Make Paned Window from the Layout menu or
from the interface or Module Browser pop-up menu (displayed by pressing mouse
button 3).</para>
<para>The paned window will be created.</para>
</listitem></orderedlist>
<note>
<para>If one of the panes is attached to the right (East) edge of its parent
and one or more of the other panes are not attached to the right edge of
the parent, the right edge of the panes <symbol role="Variable">not</symbol>
attached to the right edge will be attached to the right edge. A message
dialog box will be displayed, explaining that the children of the paned window
have different East attachments and that the East attachment has been set
to that of the rightmost pane. You can adjust the right attachment in the
Attachments Editor. Click OK.</para>
</note>
</sect2>
<sect2 id="ABUG.crobj.div.10" role="Procedure">
<title id="ABUG.crobj.mkr.9">To Add a Pane to a Paned Window<indexterm><primary>paned windows</primary><secondary>adding pane to</secondary></indexterm><indexterm><primary>adding</primary><secondary>pane to paned window</secondary></indexterm></title>
<orderedlist><listitem><para>Drop a pane on the paned window.<indexterm>
<primary>panes</primary><secondary>adding to paned window</secondary></indexterm></para>
<para>A message dialog box will be displayed, giving you the option to include
the new pane as a child of the control pane (if you drop a text pane, draw
area pane, or a term pane on a control pane), create as a layered pane, or
to add it to the paned window.</para>
</listitem><listitem><para>Click Pane to add the pane to the paned window.
</para>
<para>The new pane will be added to the bottom of the paned window.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.11" role="Procedure">
<title id="ABUG.crobj.mkr.10">To Unmake a Paned Window<indexterm><primary>paned windows</primary><secondary>unmaking</secondary></indexterm><indexterm><primary>unmaking</primary><secondary>paned windows</secondary></indexterm></title>
<orderedlist><listitem><para>Select the paned window.</para>
<para>Select a paned window by clicking at its edge. Be sure you select the
paned window and not one of its panes. You will know you have selected the
paned window if a dark box is drawn around the paned window.</para>
<para><emphasis>Or</emphasis>, open the Module Browser and select the paned
window there. This is the easiest, surest way to select a paned window.
</para>
</listitem><listitem><para>Choose Unmake Paned Window from the Layout menu
or from the pop-up menu in the interface or the Module Browser (displayed
by pressing mouse button 3).</para>
<para>The panes that made up the paned window will become separate panes
again.</para>
</listitem></orderedlist>
</sect2>
</sect1>
<sect1 id="ABUG.crobj.div.12">
<title id="ABUG.crobj.mkr.11">Creating and Editing Menus</title>
<para>A <symbol role="Variable">menu</symbol> is a list of items with meaningful
labels. Each item is connected to a function which is performed when the
menu is displayed and the item is selected. This section explains how to
create and edit menus, how to attach menus to objects, and how to connect
menu items to programmatic functions.<indexterm><primary>menus</primary>
<secondary>definition of</secondary></indexterm></para>
<para>Menus can be attached to menu buttons, menubar items, lists, and any
of the four types of panes. A menu is automatically attached to an option
menu, so there is no need to attach a menu to it.</para>
<sect2 id="ABUG.crobj.div.13">
<title id="ABUG.crobj.mkr.12">Menu Property Editor<indexterm><primary>Menu Property Editor</primary></indexterm></title>
<para>The Menu Property Editor is used to create menus. A menu, unlike most
of the objects edited in the Revolving Property Editor, is a created object
and is not available from the object palettes.</para>
<para>Only properties unique to a menu object are described here. See <!--Original
XRef content: '&xd2;Property
Editor: Universal Properties&xd3; on page&numsp;136'--><xref role="SecTitleAndPageNum"
linkend="ABUG.apRPE.mkr.2"> for descriptions of Object Type, Objects, Object
Name, and Color. See <!--Original XRef content: '&xd2;Property Editor: Common
Properties&xd3;
on page&numsp;137'--><xref role="SecTitleAndPageNum" linkend="ABUG.apRPE.mkr.3">
for descriptions of Items, Label, and Item State (Active).</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="356*">
<tbody>
<row>
<entry><para>Add New Menu</para></entry>
<entry><para>Adds a new menu to the list of menus.</para></entry></row>
<row>
<entry><para>Edit</para></entry>
<entry><para>Performs edit functions (Cut, Copy, Paste, Delete) on the selected
item in the list of menu objects. Cut and Copy place the selected item in
a buffer, ready for Paste. Delete removes the item, but does not place it
in a buffer.</para></entry></row>
<row>
<entry><para>Tearoff</para></entry>
<entry><para><indexterm><primary>menus</primary><secondary>Tearoff property</secondary></indexterm>Specifies whether tearoff is Enabled or Disabled.
If tearoff is enabled the selected menu will be &ldquo;postable.&ldquo;
That is, the menu will be displayed until you explicitly dismiss it if you
click on the Tearoff indicator (a dotted line).<indexterm><primary>Tearoff
menu property</primary></indexterm></para></entry></row>
<row>
<entry><para>Item Label Type</para></entry>
<entry><para><indexterm><primary>Item Label Type property</primary></indexterm><indexterm>
<primary>menus</primary><secondary>Item Label Type for</secondary></indexterm>Specifies
the type of label (String, Graphic, or Separator) for the item selected in
the Items list. If Graphic is chosen, Label becomes Graphic Filename. If
Separator is chosen, Label or Graphic Filename becomes inactive and Line
Style becomes active. A Separator menu item is used to create a visual division
in a menu, such as that seen in the Editors menu of the App Builder primary
window.</para></entry></row>
<row>
<entry><para>Item Mnemonic</para></entry>
<entry><para><indexterm><primary>item mnemonic</primary></indexterm><indexterm>
<primary>menu items</primary><secondary>mnemonics for</secondary></indexterm>Specifies
one of the letters in the selected item as a keyboard shortcut for choosing
the item when the menu is posted. The letter specified will be underlined.
Pressing the mnemonic letter when the menu is posted causes that item to
be chosen. Note that case is significant and that a particular letter can
be used as a mnemonic only once within a menu.</para></entry></row>
<row>
<entry><para>Accelerator</para></entry>
<entry><para><indexterm><primary>accelerator for menu item</primary></indexterm><indexterm><primary>menu items</primary><secondary>accelerator for</secondary></indexterm>Specifies
a keyboard shortcut for choosing the selected item. An accelerator is comprised
of a prefix (Ctrl, Alt, Meta, or Shift), <filename>&lt;key></filename>, and
a letter (uppercase or lowercase). To make Control-x an accelerator, for
instance, type <filename>Ctrl&lt;key>x</filename>.
<?Pub _newline>When you display the menu in test mode or in the compiled application,
Ctrl+x will be included to the right of the menu item label. If you press
the Control key and type x with focus in the window that contains the menu,
the action specified in the menu item will be performed.
<?Pub _newline>You can combine the Shift key with one of the other keys to
form a compound prefix, if you wish. To make Shift Control-x an accelerator,
type <command>Shift Ctrl&lt;key>x</command>.</para></entry></row>
<row>
<entry><para>Line Style</para></entry>
<entry><para><indexterm><primary>line style for separator</primary></indexterm><indexterm>
<primary>menus</primary><secondary>style for separator line</secondary></indexterm>Specifies
the type of line style for the selected separator item; active only when
Item Label Type is Separator. Choices are None, Etched In, Etched Out, Etched
In Dash, Etched Out Dash, Single Line, Double Line, Single Dashed Line,
and Double Dashed Line. A separator of the chosen line style will be displayed
in the menu instead of a graphic or text label.</para></entry></row>
<row>
<entry><para>Item SubMenu</para></entry>
<entry><para>A menu button and a text field for attaching, de-attaching,
creating, or editing a submenu for the selected item in the Items list. If
a submenu is attached to the selected item, the name of the submenu will
be displayed in the text field. Not valid for separator item type.</para></entry>
</row>
</tbody></tgroup></informaltable>
</sect2>
<sect2 id="ABUG.crobj.div.14" role="Procedure">
<title id="ABUG.crobj.mkr.13">To Create a Menu<indexterm><primary>menus</primary><secondary>creating &lt;$startrange></secondary></indexterm><indexterm><primary>creating</primary><secondary>menus &lt;$startrange></secondary></indexterm></title>
<para>This description assumes you are creating a menu and attaching it to
an interface object as two separate procedures. To combine these procedures,
see <!--Original XRef content: '&xd2;To Create and Attach a Menu&xd3; on
page&numsp;51'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.16">.
</para>
<note>
<para>Menus are available within modules only. Be sure the menu created is
in the same module as the object you wish to attach the menu to. Menus are
created in the <emphasis>current module</emphasis>, which is determined by
what is selected in the interface. The Editing Module field in the object
information area of the App Builder primary window indicates the current
module.<indexterm><primary>menus</primary><secondary>and modules</secondary>
</indexterm></para>
</note>
<orderedlist>
<listitem><para>Display the Menu Property Editor by choosing
Menus from the Editors menu in the App Builder primary window.</para>
<para><emphasis>Or</emphasis>, display the Revolving Property Editor and choose
Menu as the Object Type.</para>
<para>Choosing Menus from the Editors menu in the primary window is the same
as clicking the Tear-off button in the Revolving Property Editor when the
Object Type is Menu.</para>
<para>See <!--Original XRef content: '&xd2;Menu Property Editor&xd3; on page&numsp;45'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.12"> for a description of
the editor.</para>
<para>If no menus exist in the current project, the Menu Objects list will
be blank and only the Add New Menu and Edit buttons will be active.</para>
<para>If any menus exist in the current project, they will be listed in the
Menu Objects list. One of the menus will be selected in the list and the
menu's properties will be displayed for editing.</para>
</listitem>
<listitem><para>Click Add New Menu.</para>
<para>A menu will be created with a default Object Name (&ldquo;menu,&rdquo;
&ldquo;menu2,&rdquo; and so on, depending on how many menus there are in
the current module), and with two items in the Items list (&ldquo;Item1&rdquo;
and &ldquo;Item2&rdquo;). The menu will be added to the end of the Menu Objects
list, with the name of the current module preceding the menu name. The menu
will have default values for Object Name, Tearoff, Items, Item Label Type,
Label, and Item State.</para>
<para>If you know you are going to need a number of menus, you could create
them all at the same time by clicking Add New Menu the appropriate number
of times. You can also create menus that will be used as submenus, to be
attached to menu items, at this time.</para>
</listitem>
<listitem><para>Edit the menu, as described in <!--Original XRef
content: '&xd2;To Edit a Menu&xd3; on page&numsp;48'--><xref role="SecTitleAndPageNum"
linkend="ABUG.crobj.mkr.14">.</para>
<para>You can edit the menu immediately after creating it or you can edit
it later.</para>
</listitem></orderedlist>
<para>After you have created and edited a menu you will want to attach it
to an interface object and make the menu functional by creating connections
between menu items and specific actions. See <!--Original XRef content:
'&xd2;To Attach an Existing Menu to an
Object&xd3; on page&numsp;50'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.15">
and <!--Original XRef content: '&xd2;Connecting Menu Items to Actions&xd3;
on page&numsp;74'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.9">
for instructions. See <!--Original XRef content: '&xd2;To Attach an Existing
Submenu to a Menu Item&xd3; on page&numsp;52'--><xref role="SecTitleAndPageNum"
linkend="ABUG.crobj.mkr.17"> if you want to attach a submenu to a menu item.<indexterm>
<primary>menus</primary><secondary>creating &lt;$endrange></secondary></indexterm><indexterm><primary>creating</primary>
<secondary>menus &lt;$endrange></secondary></indexterm></para>
</sect2>
<sect2 id="ABUG.crobj.div.15" role="Procedure">
<title id="ABUG.crobj.mkr.14">To Edit a Menu<indexterm><primary>menus</primary><secondary>editing properties of &lt;$startrange></secondary></indexterm><indexterm><primary>editing</primary><secondary>menu properties &lt;$startrange></secondary></indexterm></title>
<para>After creating a menu you will need to edit the menu: add menu items,
give the menu items meaningful names, add submenus, and so on.</para>
<orderedlist>
<listitem><para>Display the Menu Property Editor by choosing
Menus from the Editors menu in the App Builder primary window.</para>
<para><emphasis>Or</emphasis>, display the Revolving Property Editor and choose
Menu as the Object Type.</para>
<para>See <!--Original XRef content: '&xd2;Menu Property Editor&xd3; on page&numsp;45'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.12"> for a description of
the editor.</para>
</listitem>
<listitem><para>Change Object Name, if necessary.</para>
<para>The automatically-generated Object names, which are unique within modules,
do not usually need to be changed.</para>
</listitem>
<listitem><para>Click Enabled to enable the Tearoff function, if
necessary.</para>
<para>This will make the menu &ldquo;postable,&rdquo; meaning that if you
click on the Tearoff indicator (a dotted line) the menu will not be dismissed
as soon as you select a menu item. The menu will remain posted until you
dismiss it.</para>
</listitem>
<listitem><para>Add menu items to the Items list, if necessary.
</para>
<para>Click Add Item to add an item after the selected item; choose from the
Edit menu button to perform other edit functions.</para>
</listitem><listitem><para>Change Item Label Type for menu items in the Items
list, if necessary.</para>
<para>Choices are String (text), Graphic, or Separator. Label becomes Graphic
Filename if Graphic is chosen; Line Style becomes active if Separator is
chosen.</para>
</listitem>
<listitem><para>Type a different Label or Graphic Filename for
the selected item, if necessary.</para>
<note>
<para>The easiest way to edit labels for menu items is to select the first
one in the Items list, thus selecting it in the Label field. Type a new name
and click Return. The new name will be displayed in the Items list and the
next item in the list will be selected. Continue down the list with this
select, type, Return process until all labels are completed.</para>
</note>
<para>If Graphic Item Label Type was chosen, the Graphic Filename must be
an <command>xpm</command> or <command>xbm</command> graphic file.</para>
</listitem>
<listitem><para>Type an Item Mnemonic, if necessary.</para>
<para>Type one of the letters in the item label. That letter will be underlined
in the menu item label. If the menu is posted, pressing that key will cause
the action connected with the menu item to be performed.</para>
<note>
<para>The same mnemonic letter, regardless of case, cannot be used more than
once in a menu.</para>
</note>
</listitem>
<listitem><para>Type an Accelerator, if necessary.</para>
<para>An accelerator is comprised of a prefix (Ctrl, Alt, Meta, or Shift), <filename>&lt;key></filename>, and a letter (uppercase or lowercase). See <!--Original
XRef content: '&xd2;Menu Property Editor&xd3; on page&numsp;45'--><xref role="SecTitleAndPageNum"
linkend="ABUG.crobj.mkr.12"> for more information.</para>
</listitem>
<listitem><para>Choose a Line Style, if Item Label Type is Separator.
</para>
<para>See <!--Original XRef content: '&xd2;Menu Property Editor&xd3; on page&numsp;45'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.12"> for the list of choices.
</para>
</listitem>
<listitem><para>Attach an Item Submenu, if appropriate.</para>
<para>See <!--Original XRef content: '&xd2;To Attach an Existing Submenu
to a Menu Item&xd3; on page&numsp;52'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.17">
for instructions.</para>
</listitem>
<listitem><para>Change Item State, if necessary.</para>
<para>By default the item state is Active. If you want the menu item to be
inactive when the application is started, click the Active check box to deselect
it.</para>
</listitem>
<listitem><para>Select Background and Foreground Colors, if necessary.
</para>
<para>Type in a color or choose Color Chooser from the menu and select a color
from the Color Chooser. See <!--Original XRef content: '&xd2;To Select Colors
from the Color Chooser&xd3; on
page&numsp;34'--><xref role="SecTitleAndPageNum" linkend="ABUG.edprp.mkr.5">
for details.</para>
</listitem>
<listitem><para>Click Connections to add programmatic connections
to menu items, as necessary.</para>
<para>See <!--Original XRef content: '&xd2;Connecting Menu Items to Actions&xd3;
on page&numsp;74'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.9">
for instructions.</para>
</listitem>
<listitem><para>Click Apply or OK to apply the changes.</para>
<para>If you click Apply the property editor will remain displayed.<indexterm>
<primary>menus</primary><secondary>editing properties of &lt;$endrange></secondary></indexterm><indexterm><primary>editing</primary>
<secondary>menu properties &lt;$endrange></secondary></indexterm></para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.16" role="Procedure">
<title id="ABUG.crobj.mkr.15">To Attach an Existing Menu to an Object<indexterm><primary>menus</primary><secondary>attaching to objects</secondary></indexterm><indexterm><primary>attaching</primary><secondary>menu to object</secondary></indexterm></title>
<para>The following instructions assume you have created one or more menus
as described in <!--Original XRef content: '&xd2;To Create a Menu&xd3; on
page&numsp;47'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.13">
and that you are ready to attach a menu to an object in the interface. Menus
can be attached to menu buttons, menubar items, lists, and any of the four
types of panes. A menu is automatically attached to an option menu, so there
is no need to attach a menu to it.</para>
<orderedlist>
<listitem><para>Display the Revolving Property Editor with the
object to which you wish to attach a menu selected in the editor.</para>
<para>Double-click the object in the interface or the Module Browser or choose
the appropriate Object Type in the Revolving Property Editor and select the
desired object in the Objects list.</para>
</listitem>
<listitem><para>Select a menu to attach to the selected object.
</para>
<para>Click mouse button 2 or press mouse button 1 or 3 on the Popup Menu
or Pulldown Menu menu button. Choose the appropriate menu from the Menus
submenu.</para>
<graphic id="ABUG.crobj.igrph.2" entityref="ABUG.crobj.fig.2"></graphic>
<para>The name of the selected menu will be displayed in the text field of
the Popup Menu or Pulldown Menu.</para>
</listitem>
<listitem><para>Click OK or Apply.</para>
<para>The menu will be attached to the selected object. See <!--Original
XRef content: '&xd2;Making Connections
Between Objects&xd3; on page&numsp;72'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.7">
for instructions for making the menu functional.</para>
</listitem></orderedlist>
<note>
<para>If you attach a menu to one of the pane objects or to a list, the menu
will be a pop-up menu, displayed in test mode or in the compiled application
by pressing mouse button 3 with the cursor on the pane or the list.</para>
</note>
</sect2>
<sect2 id="ABUG.crobj.div.17" role="Procedure">
<title id="ABUG.crobj.mkr.16">To Create and Attach a Menu<indexterm><primary>attaching</primary><secondary>menu while creating &lt;$startrange></secondary></indexterm><indexterm><primary>creating</primary><secondary>menu while attaching &lt;$startrange></secondary></indexterm><indexterm><primary>menus</primary><secondary>creating and attaching in one procedure &lt;$startrange></secondary></indexterm></title>
<para>One method of creating and attaching a menu to an object is described
in <!--Original XRef content: '&xd2;To
Create a Menu&xd3; on page&numsp;47'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.13">
and <!--Original XRef content: '&xd2;To Attach an Existing Menu to an Object&xd3;
on
page&numsp;50'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.15">.
With the method described here you create and attach the menu at one time.
Use whichever method is most convenient.</para>
<orderedlist>
<listitem>
<para>Display the Revolving Property Editor with the
object to which you wish to attach a menu selected in the editor.</para>
<para>Double-click the object in the interface or the Module Browser or choose
the appropriate Object Type in the Revolving Property Editor and select the
desired object in the Objects list.</para></listitem>
<listitem>
<para>Choose Create New Menu from the Pulldown Menu or
Popup Menu button available for some objects.</para>
<para>Pulldown menus are available for menu buttons and menu bars. Popup
menus are available for all pane objects and for lists. An Item SubMenu is
available for menus themselves.</para>
<para>The Menu Property Editor will be displayed, with a newly-created menu
selected in the Menu Objects list. The menu will have default values for
Object Name, Tearoff, Items, Item Label Type, Label, and Item State.</para>
<para>The Object Name will be of the form &ldquo;object_type_menu,&rdquo;
&ldquo;object_type_menu2,&rdquo; and so on., depending on what type of object
was selected in the property editor when Create New Menu was chosen and
how many menus have been created for the current module. The menu will be
added to the end of the Menu Objects list, with the name of the current module
preceding the menu name.</para></listitem>
<listitem><para>Edit the menu and click OK to apply the changes
and dismiss the Menu Property Editor.</para>
<para>See <!--Original XRef content: '&xd2;To Edit a Menu&xd3; on page&numsp;48'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.14"> for instructions. You
can edit the menu later if you like.</para>
</listitem>
<listitem><para>Click Apply or OK in the Revolving Property Editor
to attach the menu to<literal><indexterm><primary>creating</primary><secondary>menu while attaching &lt;$endrange></secondary></indexterm></literal> <literal><indexterm><primary>attaching</primary><secondary>menu while creating &lt;$endrange></secondary></indexterm></literal>the selected object.</para>
<para>See <!--Original XRef content: '&xd2;Making Connections Between Objects&xd3;
on page&numsp;72'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.7">
for instructions for making the menu functional. <literal><indexterm><primary>menus</primary><secondary>creating and attaching in one procedure &lt;$endrange></secondary></indexterm></literal></para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.18" role="Procedure">
<title id="ABUG.crobj.mkr.17">To Attach an Existing Submenu to a Menu Item<indexterm><primary>submenus</primary><secondary>attaching to menu items</secondary></indexterm><indexterm><primary>attaching</primary><secondary>submenu to menu item</secondary></indexterm></title>
<para>The following instructions assume you have created two or more menus
as described in <!--Original XRef content: '&xd2;To Create a Menu&xd3; on
page&numsp;47'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.13">
and that you are ready to attach one of them as a submenu for a menu item.
</para>
<orderedlist>
<listitem>
<para>Display the Menu Property Editor or the Revolving
Property Editor with Menu chosen as the Object Type.</para></listitem>
<listitem>
<para>In the Menu Objects or Objects list select the
menu that contains the menu item to which you want to attach a submenu.</para>
</listitem>
<listitem>
<para>In the Items list select the menu item to which
you want to attach a submenu.</para></listitem>
<listitem><para>Select a menu to attach to the selected menu item.
</para>
<para>Click mouse button 2 or press mouse button 1 or 3 on the Item SubMenu
menu button. Choose the appropriate menu from the Menus submenu.</para>
<graphic id="ABUG.crobj.igrph.3" entityref="ABUG.crobj.fig.3"></graphic>
<para>The name of the selected menu will be displayed in the text field of
the Item SubMenu.</para></listitem>
<listitem><para>Click OK or Apply.</para>
<para>The submenu will be attached to the selected menu item. See <!--Original
XRef content: '&xd2;Making
Connections Between Objects&xd3; on page&numsp;72'--><xref role="SecTitleAndPageNum"
linkend="ABUG.afunc.mkr.7"> for instructions for making the submenu functional.
</para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.19" role="Procedure">
<title>To Create and Attach a Submenu<indexterm><primary>attaching</primary><secondary>submenu while creating &lt;$startrange></secondary></indexterm><indexterm><primary>submenus</primary><secondary>creating and attaching in one procedure &lt;$startrange></secondary></indexterm><indexterm><primary>creating</primary><secondary>submenu while attaching &lt;$startrange></secondary></indexterm></title>
<para>The following instructions assume you have created one or more menus
and that you want to create and attach a submenu to one of the items in one
of the menus. With this method you create the submenu and attach it as part
of a single procedure. Another method for accomplishing this task is to create
the menu as described in <!--Original XRef content: '&xd2;To Create a Menu&xd3;
on page&numsp;47'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.13">
and to attach it to a menu item as described in <!--Original XRef content:
'&xd2;To Attach an Existing Submenu to a Menu Item&xd3; on
page&numsp;52'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.17">.
Use whichever method is most convenient.</para>
<note>
<para>When you create and attach a submenu you will be using two editors&mdash;one
to create the menu and the other to attach the submenu to the menu item.
If you start this procedure in the Menu Property Editor, you will be attaching
the submenu in the Menu Property Editor but creating it in the Revolving
Property Editor. If you start the procedure in the Revolving Property Editor,
you will be attaching the menu there but creating it in the Menu Property
Editor. The example below assumes you are starting the procedure in the Menu
Property Editor.</para>
</note>
<orderedlist>
<listitem><para>Display the Menu Property Editor by choosing
Menus from the Editors menu of the App Builder primary window.</para>
</listitem><listitem><para>In the Objects list select the menu that contains
the menu item to which you want to attach a submenu.</para>
</listitem><listitem><para>In the Items list select the menu item to which
you want to attach a submenu.</para>
</listitem><listitem><para>Choose Create New Menu from the Item SubMenu menu.
</para>
<para>The Revolving Property Editor will be displayed, with the new menu
selected in the Objects list.</para>
</listitem><listitem><para>Edit the menu and click OK to apply the editing
changes you made and to dismiss the Revolving Property Editor</para>
<para>See <!--Original XRef content: '&xd2;To Edit a Menu&xd3; on page&numsp;48'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.14"> for instructions. You
can edit the menu later if you like.</para>
</listitem><listitem><para>Click Apply in the Menu Property Editor to attach
the submenu to the menu<literal><indexterm><primary>creating</primary><secondary>submenu while attaching &lt;$endrange></secondary></indexterm></literal> <literal><indexterm><primary>attaching</primary><secondary>submenu while creating &lt;$endrange></secondary></indexterm></literal>item selected in Step 2.
See <!--Original XRef content: '&xd2;Connecting Menu Items to Actions&xd3;
on page&numsp;74'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.9">
for instructions for making the submenu functional. <literal><indexterm>
<primary>submenus</primary><secondary>creating and attaching in one procedure &lt;$endrange></secondary></indexterm></literal></para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.20" role="Procedure">
<title id="ABUG.crobj.mkr.18">To Create and Attach a Help Menu</title>
<para>A help menu at the right end of the menu bar in the application primary
main window is a common feature of applications. Do the following to create
a help menu and attach it to the Help item of a menu bar. These instructions
assume you have included a menu bar in the primary main window and that Help
is one of the menu bar items.</para>
<orderedlist>
<listitem>
<para>Display the Revolving Property Editor with Menubar
selected in the editor.</para>
<para>Double-click the appropriate menu bar in the interface or the Module
Browser or choose Menubar from the Object Type menu in the Revolving Property
Editor and select the desired menu bar in the Objects list. This will normally
be the menu bar in the primary main window.</para>
</listitem><listitem><para>Select Help in the Items list.</para>
<para>This is the Help item on the menu bar.</para>
</listitem>
<listitem><para>Click mouse button 2 or press mouse button 1 or
3 on the Pulldown Menu menu button. Choose Create New Menu from the Menus
submenu.</para>
<para>The name of the new menu will be displayed in the text field of the
Pulldown Menu and the Menu Property Editor will be displayed with the new
menu loaded.</para>
</listitem>
<listitem><para>Edit the menu.</para>
<orderedlist>
<listitem><para>If you want a Help menu that looks like the App
Builder Help menu, for instance, add four items to the two default items
in the Items list. Select each item in turn and type appropriate labels (Overview,
Tasks, Reference, On Item, Using Help, and About [<emphasis>application_name</emphasis> ], for instance).</para>
</listitem>
<listitem><para>Add item mnemonics and accelerators, if appropriate.
</para>
<para>See <!--Original XRef content: '&xd2;Menu Property Editor&xd3; on page&numsp;45'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.12"> for details.</para>
</listitem><listitem><para>Make other changes to the menu, if appropriate.
</para>
</listitem>
</orderedlist>
</listitem>
<listitem><para>Click OK or Apply in the Menu Property Editor.
</para>
<para>The menu is complete. The Menu Property Editor will be dismissed if
you click OK.</para>
</listitem>
<listitem><para>Click OK or Apply in the Revolving Property Editor.
</para>
<para>The Help menu has been attached to the Help item in the menu bar. The
Revolving Property Editor will be dismissed if you click OK.</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="ABUG.crobj.div.21">
<title id="ABUG.crobj.mkr.19">Creating and Editing Messages</title>
<para>This section describes the Message Editor and explains how to create
and edit message dialog boxes.</para>
<sect2 id="ABUG.crobj.div.22">
<title id="ABUG.crobj.mkr.20">Message Editor</title>
<para><indexterm><primary>Message Editor &lt;$startrange></primary></indexterm>The Message Editor is used to create
various types of messages to be displayed at appropriate times in the compiled
application. It is shown in <!--Original XRef content: 'Figure&numsp;5&hyphen;1'--><xref
role="CodeOrFigureOrTable" linkend="ABUG.crobj.mkr.21"> and then described.
See <!--Original XRef content: '&xd2;To Create a Message Dialog Box&xd3;
on page&numsp;58'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.22">
and <!--Original XRef content: '&xd2;To Edit
a Message&xd3; on page&numsp;59'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.23">
for instructions on its use.<indexterm><primary>editor</primary><secondary>Message &lt;$startrange></secondary>
</indexterm></para>
<figure>
<title id="ABUG.crobj.mkr.21">Message Editor</title>
<graphic id="ABUG.crobj.grph.1" entityref="ABUG.crobj.fig.4"></graphic>
</figure>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="356*">
<tbody>
<row>
<entry><para>Messages</para></entry>
<entry><para>Lists all messages for the current project. The module name
precedes the message name in the list.</para></entry></row>
<row>
<entry><para>Module menu</para></entry>
<entry><para>Specifies the module for which you wish to add a new message.
The module name precedes the message name in the Messages list.</para></entry>
</row>
<row>
<entry><para>Add Message</para></entry>
<entry><para>Adds a new message to the Messages list and to the current project.
The message is for the module selected in the module option menu.</para></entry>
</row>
<row>
<entry><para>Delete Message</para></entry>
<entry><para>Deletes the selected message.</para></entry></row>
<row>
<entry><para>Name</para></entry>
<entry><para>Specifies the instance name of the current message object. Messages
are given names such as &ldquo;message,&rdquo; &ldquo;message2,&rdquo;
&ldquo;message3,&rdquo; by default.</para></entry></row>
<row>
<entry><para>Dialog Title</para></entry>
<entry><para>Specifies the title that will appear at the top of the message
dialog box.</para></entry></row>
<row>
<entry><para>Type</para></entry>
<entry><para>Specifies the type of message to be created. The choices are
Error, Information, Working, Question, and Warning. The message type appears
above the message text pane. The appropriate message icon appears in the
message dialog box in the compiled applications.</para></entry></row>
<row>
<entry><para>Message text pane</para></entry>
<entry><para>A text pane for entering the text of the message. Press Return
when you want the text to start a new line. The label above the text pane
varies, depending on what type of message you have chosen.</para></entry>
</row>
<row>
<entry><para>Button check boxes</para></entry>
<entry><para>Specifes which buttons will be included at the bottom of the
message dialog box. Each message type has a different set of buttons specified
by default; these default choices can be changed. Actions associated with
the Action1, Action2, Action3, and Cancel buttons are set in the Connections
Editor. See <!--Original XRef content: '&xd2;To Create a Message Dialog
Box&xd3; on page&numsp;58'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.22">
for detailed instructions.</para></entry></row>
<row>
<entry><para>Default Button menu</para></entry>
<entry><para>Specifies the default button for the selected message dialog.
</para></entry></row>
<row>
<entry><para>Connections</para></entry>
<entry><para>Displays the Connections Editor for specifying what functions
to call for each of the Action buttons and the Cancel button.</para></entry>
</row>
<row>
<entry><para>Help Text</para></entry>
<entry><para>Displays the Help Editor, in which you write help text to be
displayed when the Help button is clicked in the message dialog box.</para></entry>
</row>
<row>
<entry><para>Show Dialog</para></entry>
<entry><para>A push button for displaying the selected message in a message
dialog box that looks like the actual dialog box in the compiled application.
Click one of the buttons other than Help to dismiss the dialog box.</para></entry>
</row>
</tbody></tgroup></informaltable>
<para>See <!--Original XRef content: '&xd2;Property Editor: Common Buttons&xd3;
on page&numsp;139'--><xref role="SecTitleAndPageNum" linkend="ABUG.apRPE.mkr.4">
for descriptions of the buttons at the bottom of the editor.<indexterm>
<primary>Message Editor &lt;$endrange></primary></indexterm><indexterm><primary>editor</primary><secondary>Message &lt;$endrange></secondary></indexterm></para>
</sect2>
<sect2 id="ABUG.crobj.div.23" role="Procedure">
<title id="ABUG.crobj.mkr.22">To Create a Message Dialog Box<indexterm><primary>messages</primary><secondary>creating &lt;$startrange></secondary></indexterm><indexterm><primary>creating</primary><secondary>messages &lt;$startrange></secondary></indexterm><indexterm><primary>message dialog box, &lt;Emphasis>See &lt;Default Para Font> messages &lt;$nopage></primary></indexterm></title>
<para>See <!--Original XRef content: '&xd2;Message Editor&xd3; on page&numsp;56'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.20"> for descriptions of
each of the fields in the editor. See <!--Original XRef content: '&xd2;To
Connect a Non-Modal Message to a Function&xd3; on page&numsp;60'--><xref role="SecTitleAndPageNum"
linkend="ABUG.crobj.mkr.24"> for a discussion of how to connect messages
to the functions that cause them to be displayed, with examples.</para>
<orderedlist>
<listitem><para>Choose Messages from the Editors menu of the
App Builder primary window to display the Message Editor.</para>
</listitem><listitem><para>Choose the module to which you want to add a message
in the option menu below the Messages list.</para>
</listitem>
<listitem><para>Click Add Message.<indexterm><primary>modules</primary><secondary>adding message to</secondary></indexterm><indexterm>
<primary>messages</primary><secondary>adding to module</secondary></indexterm></para>
<para>A unique name (&ldquo;message,&rdquo; &ldquo;message2,&rdquo; and so
on, depending on how many messages are in the current module) will be displayed
in the Name field. The module name and the message name will be added to
the Messages list.</para>
</listitem>
<listitem><para>Modify the Name if you wish.</para>
<para>This is the name used to identify the message internally&mdash;in the
Connections Editor, for instance. This name is not displayed in the compiled
message dialog box.<indexterm><primary>messages</primary><secondary>naming</secondary></indexterm><indexterm><primary>naming</primary><secondary>messages</secondary></indexterm></para>
</listitem>
<listitem>
<para>Type a title for the message dialog in the Dialog
Title field.</para>
<para>This will appear in the title bar of the compiled message dialog box.
</para>
</listitem>
<listitem><para>Choose a message type from the Type menu.<indexterm>
<primary>messages</primary><secondary>selecting type of</secondary></indexterm><indexterm>
<primary>selecting</primary><secondary>message type</secondary></indexterm><indexterm>
<primary>message types</primary></indexterm></para>
<para>The icon for the message type will be displayed in the Type menu and
the message type (Error, Information, Working, Question, or Warning) will
be displayed above the message text pane (to the right of the Type menu).
</para>
</listitem>
<listitem><para>Type the message text in the message text pane,
pressing Return when you want a new line to start in the compiled message.<indexterm><primary>messages</primary><secondary>entering text for</secondary>
</indexterm>
</para>
</listitem>
<listitem><para>Specify which buttons will appear in the message
dialog box by clicking the check boxes below the message text pane and typing
the labels you want on the Action1, Action2, and Action3 buttons.</para>
<para>Each of the message types includes a default set of buttons that you
can modify:<indexterm><primary>messages</primary><secondary>default button
sets for</secondary></indexterm><indexterm><primary>default button sets for
messages</primary></indexterm></para>
<itemizedlist remap="Bullet2">
<listitem><para>Error: Action2 (Retry), Cancel,
Help.</para>
</listitem>
<listitem><para>Information: Action1 (OK), Help.</para>
</listitem>
<listitem><para>Working: Action1 (Close), Action2 (Stop), Help.
</para>
</listitem>
<listitem><para>Question: Action1 (Yes), Action2 (No), Help.</para>
</listitem>
<listitem><para>Warning: Action2 (Continue), Cancel, Help.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>Choose a default button from the Default Button
menu.<indexterm><primary>default buttons</primary><secondary>for messages</secondary></indexterm><indexterm><primary>messages</primary><secondary>default button for</secondary></indexterm></para>
<para>This is the button that will have an extra border when the message dialog
box is displayed. This is the button that will be activated if Return is
pressed. Each of the message types has a default Default Button that you
can modify:</para>
<itemizedlist remap="Bullet2"><listitem><para>Error: Action2</para>
</listitem><listitem><para>Information: Action1</para>
</listitem><listitem><para>Working: Action1</para>
</listitem><listitem><para>Question: Action1</para>
</listitem><listitem><para>Warning: Action2</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>Click the Help Text button and create help text,
as appropriate.</para>
<para>See <!--Original XRef content: '&xd2;To Create Help&xd3; on page&numsp;68'--><xref
role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.4"> for instructions.<indexterm>
<primary>creating</primary><secondary>messages &lt;$endrange></secondary></indexterm><indexterm><primary>messages</primary>
<secondary>creating &lt;$endrange></secondary></indexterm></para>
</listitem><listitem><para>Click OK or Apply to apply the changes.</para>
<para>The Message Editor will be dismissed if you click OK.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.24" role="Procedure">
<title id="ABUG.crobj.mkr.23">To Edit a Message<indexterm><primary>messages</primary><secondary>editing properties of</secondary></indexterm><indexterm><primary>editing</primary><secondary>message properties</secondary></indexterm></title>
<orderedlist>
<listitem><para>Choose Messages from the Editors menu of the
App Builder primary window to display the Message Editor.</para>
</listitem>
<listitem><para>Select the message you want to edit in the Messages
list.</para>
</listitem>
<listitem><para>Edit the message, as appropriate.</para>
<itemizedlist remap="Bullet2"><listitem><para>To delete a message, click Delete
Message.</para>
</listitem><listitem><para>To modify the dialog box title, click in the Dialog
Title text field and type the new label.</para>
</listitem><listitem><para>To change the message type, choose a different
Type icon.</para>
</listitem><listitem><para>To modify the message text, click in the message
text pane and type the appropriate changes.</para>
</listitem><listitem><para>To change the available buttons, select the check
boxes and type new button labels, if appropriate.</para>
</listitem><listitem><para>To change the default button, choose another from
the Default Button menu.</para>
</listitem><listitem><para>To modify help text, click Help Text, make the
changes in the Help Editor, and click OK in the Help Editor.</para>
</listitem></itemizedlist>
</listitem>
<listitem><para>Click OK or Apply to apply the changes.</para>
<para>The Message Editor will be dismissed if you click OK.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.25" role="Procedure">
<title id="ABUG.crobj.mkr.24">To Connect a Non-Modal Message to a Function<indexterm><primary>messages</primary><secondary>connecting to functions</secondary></indexterm><indexterm><primary>connecting</primary><secondary>message to function</secondary></indexterm></title>
<para>See <!--Original XRef content: '&xd2;Example: Writing Code for Messages&xd3;
on page&numsp;61'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.25">
for a discussion of how to connect a message to the function that causes
it to be displayed, with examples. In particular, read that section to see
how to attach a modal (blocking) message to a function.</para>
<orderedlist><listitem><para>Display the Connections Editor by clicking Connections
in the Message Editor or by choosing Connections from the Editors menu of
the App Builder primary window.</para>
<para>If you select a message in the Message Editor and click Connections,
the selected message will be selected in the Source list of the Connections
Editor. You can skip the next two steps.</para>
</listitem><listitem><para>Display messages in the Source list by choosing
Message from the Source menu.</para>
</listitem><listitem><para>Select a message in the Source list.</para>
</listitem><listitem><para>Choose Call Function as the Action Type.</para>
<para>This activates the When menu on the Source side of the Connections Editor.
</para>
</listitem><listitem><para>Choose a When item (Action1, Action2, Action3,
or Cancel Activated, depending on which buttons were checked in the Message
Editor).</para>
</listitem><listitem><para>Type the name of the Function to be called when
the selected button is selected.</para>
<para>When code is generated, this function is created in &lt; <symbol role="Variable">module_name</symbol>><filename>_stubs.c</filename>. You will have to substitute
appropriate code before running <command>make</command>.</para>
</listitem><listitem><para>Click Connect to create the connection.</para>
<para>The connection will be displayed in the View list at the bottom of the
Connections Editor.</para>
</listitem><listitem><para>Repeat the previous three steps for each button
except Help.</para>
</listitem><listitem><para>Click Cancel to dismiss the Connections Editor.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="ABUG.crobj.div.26">
<title id="ABUG.crobj.mkr.25">Example: Writing Code for Messages</title>
<para>Once you have created a message as described in <!--Original XRef content:
'&xd2;To Create a Message Dialog
Box&xd3; on page&numsp;58'--><xref role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.22">,
you must determine when and how it should be displayed. Usually messages
are displayed after a certain piece of logic has been executed. For example,
if a user types digits in a text field that is designed to accept a name,
you will want to post an error message informing the user that digits are
not valid.</para>
<para>Message boxes in Motif can be displayed in one of two ways: <emphasis>modally</emphasis> or <emphasis>non- modally</emphasis> (equivalently, <emphasis>blocking</emphasis> or <emphasis>non-blocking</emphasis>). The App Builder
code generator (<command>dtcodegen</command>) supplies two routines, corresponding
to the two modes of display. They are found in <filename>dtb_utils.c</filename>
and are named:</para>
<itemizedlist remap="Bullet1">
<listitem><para><filename>dtb_show_modal_message()</filename></para>
</listitem>
<listitem><para><filename>dtb_show_message()</filename></para>
</listitem>
</itemizedlist>
<para>If you want to display a particular message modally, use <filename>dtb_show_modal_message()</filename>. If you want to display a particular
message non-modally, use <filename>dtb_show_message()</filename>.</para>
<para>One of the key differences in the way these two types of of messages
are handled is in how the application determines which button was pressed
by the user in the message dialog box. For non-modal messages callbacks are
added to each button via the Connections Editor. When the user clicks a button
the corresponding callback is called. Since modal dialogs are <emphasis>blocking</emphasis>, the button callbacks are <symbol role="Variable">not</symbol> called. Instead, the value is returned by <filename>dtb_show_modal_message</filename>, which indicates which button is pressed by the user.</para>
</sect2>
<sect2 id="ABUG.crobj.div.27" role="Procedure">
<title>To Write Code for Modal Messages</title>
<para>If a message is to be displayed modally, use <filename>dtb_show_modal_message()</filename>. This routine returns a value which indicates which message box
button the user has pressed. The value is an enum that is defined in <filename>dtb_utils.h</filename>:</para>
<programlisting>/*
* Returns answer value for modal MessageBox
*/
typedef enum {
   DTB_ANSWER_NONE,
   DTB_ANSWER_ACTION1,
   DTB_ANSWER_ACTION2,
   DTB_ANSWER_ACTION3,
   DTB_ANSWER_CANCEL,
   DTB_ANSWER_HELP
} DTB_MODAL_ANSWER;
</programlisting>
<para>You can then examine the return value (for example via a switch statement)
and execute the appropriate piece of code.</para>
<para>Here's an example of displaying a message modally. Say that you have
created a simple application, named <command>foo</command>. The project
is named <filename>foo.bip</filename> and consists of one module, <filename>foo.bil</filename>. The module <filename>foo.bil</filename> consists of a
main window, control pane, and two text fields, one for the user to enter
a person's first name and the other to enter the last name. If the user
types digits, an error message will be posted, informing the user that digits
are not allowed, and giving the user a couple of options. The user can start
over, which means the text entered will be erased, or the user can continue,
which means that the text entered will be left intact, giving the user discretion
as to how to modify the text.</para>
<para>A call-function connection is made for both text fields, which will
be called each time the user types something. The function for the first
text field will check if the character typed is a digit. If so, it will
post the error message modally:</para>
<programlisting>void
verify_first_nameCB(
   Widget widget,
   XtPointer clientData,
   XtPointer callData
)
{
   /*** DTB_USER_CODE_START vvv Add C variables and code below vvv ***/
   char                *text = (char *)NULL;
   int                 textlen = 0;
   DTB_MODAL_ANSWER    answer = DTB_ANSWER_NONE;
   DtbFooMainwindowInfo instance = (DtbFooMainwindowInfo) clientData;
   /*** DTB_USER_CODE_END   ^^^ Add C variables and code above ^^^ ***/

   /*** DTB_USER_CODE_START vvv Add C code below vvv ***/

   text = XmTextFieldGetString(widget);
   if ((text != NULL) &amp;&amp; (*text != NULL))
   {
       textlen = strlen(text);
       if (isdigit(text[textlen-1]))
       {
           dtb_foo_message_initialize(&amp;dtb_foo_message);
           answer = dtb_show_modal_message(instance->textfield,
                       &amp;dtb_foo_message, NULL, NULL, NULL);
           switch (answer)
           {
               case DTB_ANSWER_ACTION1:        /* Start Over */
                   XmTextFieldSetString(widget, &ldquo;&ldquo;);
                   break;

               case DTB_ANSWER_ACTION2: /* Continue */
                   break;
           }
       }
   }

   /*** DTB_USER_CODE_END   ^^^ Add C code above ^^^ ***/
}
</programlisting>
</sect2>
<sect2 id="ABUG.crobj.div.28" role="Procedure">
<title>To Write Code for Non-Modal Messages</title>
<para>If you want to post a non-modal message, use <filename>dtb_show_message()</filename>. Since this function is not modal and does not return a return
value, callbacks for the message box buttons should be specified via the
Connections Editor, as described in <!--Original XRef content: '&xd2;To
Connect a Non-Modal Message to a Function&xd3; on page&numsp;60'--><xref role="SecTitleAndPageNum"
linkend="ABUG.crobj.mkr.24">. The buttons that are specified for the message
box are displayed as When items for the message object in the Connections
Editor.</para>
<para>Using the same example as above, make the last name text field display
the error message non-modally if the user types a digit. As previously mentioned,
first you'll need to make a couple of call-function connections for the two
buttons in the message box, labelled &ldquo;Start Over&ldquo; and &ldquo;Continue.&ldquo;
When code is generated, add code to those routines to do the right thing.
The start over routine will clear out the text field and the continue routine
will do nothing, in this case.</para>
<programlisting>void
verify_last_nameCB(
   Widget    widget,
   XtPointer clientData,
   XtPointer callData
)
{
   /*** DTB_USER_CODE_START vvv Add C variables and code below vvv ***/
   char                *text = (char *)NULL;
   int                 textlen = 0;
   DtbFooMainwindowInfo instance = (DtbFooMainwindowInfo) clientData;

   /*** DTB_USER_CODE_END   ^^^ Add C variables and code above ^^^ ***/

   /*** DTB_USER_CODE_START vvv Add C code below vvv ***/

   text = XmTextFieldGetString(widget);
   if ((text != NULL) &amp;&amp; (*text != NULL))
   {
       textlen = strlen(text);
       if (isdigit(text[textlen-1]))
       {
           dtb_foo_message_initialize(&amp;dtb_foo_message);
           dtb_show_message(instance->textfield,
                       &amp;dtb_foo_message, NULL, NULL);
       }
   }

   /*** DTB_USER_CODE_END   ^^^ Add C code above ^^^ ***/
}

void
start_overCB(
   Widget widget,
   XtPointer clientData,
   XtPointer callData
)
{
   /*** DTB_USER_CODE_START vvv Add C variables and code below vvv ***/

   DtbFooMainwindowInfo instance = (DtbFooMainwindowInfo) clientData;

   /*** DTB_USER_CODE_END   ^^^ Add C variables and code above ^^^ ***/

   /*** DTB_USER_CODE_START vvv Add C code below vvv ***/

   XmTextFieldSetString(dtb_foo_mainwindow.textfield2, &ldquo;&rdquo;);

   /*** DTB_USER_CODE_END   ^^^ Add C code above ^^^ ***/
}

void
continueCB(
   Widget widget,
   XtPointer clientData,
   XtPointer callData
)
{
   /*** DTB_USER_CODE_START vvv Add C variables and code below vvv ***/
   /*** DTB_USER_CODE_END   ^^^ Add C variables and code above ^^^ ***/

   /*** DTB_USER_CODE_START vvv Add C code below vvv ***/
   /*** DTB_USER_CODE_END   ^^^ Add C code above ^^^ ***/
}
</programlisting>
<para>The two routines above, <filename>start_overCB()</filename> and <filename>continueCB()</filename>, are added as
callbacks for the two buttons via the call to <filename>dtb_show_message()</filename>. Here is the
code fragment that adds the callback (from <filename>dtb_utils.c</filename>):
</para>
<programlisting>/* Add Callbacks if necessary */
if (mbr->action1_callback != (XtCallbackProc) NULL)
    XtAddCallback(msg_dlg, XmNokCallback, mbr->action1_callback, NULL);
if (mbr->cancel_callback != (XtCallbackProc) NULL)
    XtAddCallback(msg_dlg, XmNcancelCallback, mbr->cancel_callback, NULL);
if (mbr->action2_callback != (XtCallbackProc) NULL)
{
    action_btn = dtb_MessageBoxGetActionButton(msg_dlg, DTB_ACTION2_BUTTON);
    if (action_btn != NULL)
        XtAddCallback(action_btn, XmNactivateCallback,
                      mbr->action2_callback, NULL);
}
if (mbr->action3_callback != (XtCallbackProc) NULL)
{
    action_btn = dtb_MessageBoxGetActionButton(msg_dlg, DTB_ACTION3_BUTTON);
if (action_btn != NULL)
    XtAddCallback(action_btn, XmNactivateCallback, mbr->action3_callback, NULL);
}
</programlisting>
<para>The structure <command>mbr</command> contains all the necessary information
for the message. The
structure is filled in with the values specified in the Message Editor when
the
message object was created via the <filename>dtb_&amp;_&amp;_initialize()</filename> routine&mdash;in this
example, <filename>dtb_foo_message_initialize()</filename>.</para>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:11:44-->
<?Pub *0000073736>