cde/cde/doc/C/guides/builderGuide/ch04.sgm

<!-- $XConsortium: ch04.sgm /main/6 1996/09/08 19:48:17 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.edprp.div.1">
<title id="ABUG.edprp.mkr.1">Editing Properties of Interface Objects</title>
<para>All objects dragged from the App Builder palettes have <emphasis>properties</emphasis> that can be
edited. These properties include object name, color, and a variety of other
characteristics, depending on the object type. Once you have dropped an object
or have created an object in the interface, you will want to customize the
object
by editing it in the Revolving Property Editor. See
<!--Original XRef content: 'Appendix&numsp;B, &xd2;Revolving
Property Editor'--><xref role="AppendixNumAndTitle" linkend="ABUG.apRPE.mkr.1">,
for an illustration of a property editor and descriptions of
each of the elements in all of the property editors.</para>
<informaltable id="ABUG.edprp.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Open a Property Editor32'--><xref
role="JumpText" linkend="ABUG.edprp.mkr.2"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Edit Properties of an Object32'--><xref
role="JumpText" linkend="ABUG.edprp.mkr.3"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a Fixed Property Editor33'--><xref
role="JumpText" linkend="ABUG.edprp.mkr.4"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Example: Editing Main Window Properties35'--><xref
role="JumpText" linkend="ABUG.edprp.mkr.6"></para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect1 id="ABUG.edprp.div.2" role="Procedure">
<title id="ABUG.edprp.mkr.2">To Open a Property Editor<indexterm><primary>property editor</primary><secondary>opening</secondary></indexterm><indexterm><primary>opening</primary><secondary>property editor</secondary></indexterm></title>
<itemizedlist remap="Bullet1"><listitem><para>Double-click an object in the
interface or in the Module Browser to open the Revolving Property Editor
with the clicked-on object selected.</para>
</listitem><listitem><para><emphasis>Or</emphasis>, select an object in the
interface or in the Module Browser and choose Props (Revolving or Fixed)
from the pop-up menu (displayed by pressing mouse button 3 in the interface
or the Browser) to open the property editor with the object selected.</para>
</listitem><listitem><para><emphasis>Or</emphasis>, choose Properties from
the Editors menu in the App Builder primary window.</para>
<para>The Revolving Property Editor will be displayed, with the object most
recently selected in the interface or the Module Browser selected in the
Revolving Property Editor.</para>
</listitem></itemizedlist>
<sect2 id="ABUG.edprp.div.3" role="Procedure">
<title id="ABUG.edprp.mkr.3">To Edit Properties of an Object<indexterm><primary>objects</primary><secondary>editing properties of</secondary></indexterm><indexterm><primary>editing</primary><secondary>object properties</secondary></indexterm></title>
<para>Once you have displayed the property editor, do the following to edit
the properties of an object:</para>
<orderedlist><listitem><para>Choose the object type that you want to edit
from the Object Type menu at the top of the Revolving Property Editor, if
necessary.</para>
<para>If you double-clicked an object to display the Revolving Property Editor
or if the object was selected when you chose Props from one of the pop-up
menus, the object type and the specific object will already be selected.
</para>
<para>If a tear-off (Fixed) editor is displayed, there is no Object Type menu.
</para>
</listitem><listitem><para>Select the object that you want to edit in the
Objects scrolling list, if necessary.</para>
<para>The object may already be selected.</para>
</listitem><listitem><para>Modify any of the properties, as appropriate.
</para>
<para>See <!--Original XRef content: 'Appendix&numsp;B,
&xd2;Revolving Property Edit--><!--or'--><xref role="AppendixNumAndTitle"
linkend="abug.aprpe.mkr.1">, for descriptions of each of the elements
of the property editors.</para>
<note>
<para><literal>List item editing</literal>: once you have the appropriate
number of items in the list, the easiest way to perform item editing in those
property editors that have an item list* is to select the first item in the
list, thus selecting it in the label text field. Type a new name for the
item and click Return. The new name will be displayed in the item list and
the next item in the list will be selected. Continue down the list with this
select, type, Return sequence until all items are completed. *Property
editors with item lists include the choice objects (Radio Box, Check Box,
Option Menu), Combo Box, List, Menu, Menubar, and Spin Box.</para>
</note>
</listitem><listitem><para>Click the Apply button to apply the changes and
leave the property editor displayed.</para>
<para>Click the OK button to apply the changes and close the property editor.
</para>
<para>Click Reset to reset all changed elements to their values at the last
Apply.</para>
<para>Click Cancel to reset all elements to their values at the last Apply
and close the property editor.</para>
</listitem></orderedlist>
<para>See <!--Original XRef content: '&xd2;Example: Editing Main Window Properties&xd3;
on page&numsp;35'--><xref role="SecTitleAndPageNum" linkend="ABUG.edprp.mkr.6">
for specific instructions for editing the properties of a main window.</para>
</sect2>
<sect2 id="ABUG.edprp.div.4" role="Procedure">
<title id="ABUG.edprp.mkr.4">To Display a Fixed Property Editor<indexterm><primary>tear-off property editor, displaying</primary></indexterm><indexterm><primary>fixed property editor, displaying</primary></indexterm><indexterm><primary>displaying</primary><secondary>fixed property editor</secondary></indexterm></title>
<para>The Revolving Property Editor is a single dialog box that displays one
of 20 property editors, depending on the item you choose from the Object
Type option menu. To display a separate, fixed property editor of a specific
object type:</para>
<orderedlist><listitem><para>Select the object you want to edit in the interface
or in the Module Browser. See <!--Original XRef content: '&xd2;Module Browser&xd3;
on page&numsp;128'--><xref role="SecTitleAndPageNum" linkend="ABUG.apWDB.mkr.8">
for a description of the Browser.</para>
</listitem><listitem><para>Choose Props from the pop-up menu (displayed by
pressing mouse button 3 in the interface or in the Module Browser) and select
Fixed from the Props submenu.</para>
<para>A fixed version of the property editor for the selected object type
will be displayed.</para>
</listitem></orderedlist>
<para><emphasis>Or</emphasis></para>
<orderedlist><listitem><para>Choose the object type you want to edit in the
Object Type menu of the Revolving Property Editor.</para>
</listitem><listitem><para>Click the Tear-off button at the top-right of the
Revolving Property Editor.</para>
<para>A fixed version of the property editor for the selected object type
will be displayed.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="ABUG.edprp.div.5" role="Procedure">
<title id="ABUG.edprp.mkr.5">To Select Colors from the Color Chooser<indexterm><primary>setting</primary><secondary>foreground color</secondary></indexterm><indexterm><primary>setting</primary><secondary>background color</secondary></indexterm><indexterm><primary>foreground color</primary></indexterm><indexterm><primary>background color</primary></indexterm><indexterm><primary>Color Chooser</primary></indexterm><indexterm><primary>selecting</primary><secondary>colors</secondary></indexterm></title>
<para>Most property editors have background and foreground color properties.
If you know the name of the color you want to use, type it in the text field
next to Color:Background or Color:Foreground. To select a color from the
Color Chooser palette:</para>
<orderedlist><listitem><para>Click the Background or Foreground menu button
and choose Color Chooser.</para>
<para>The Color Chooser, with an array of color choices available, will be
displayed.</para>
<graphic id="ABUG.edprp.igrph.1" entityref="ABUG.edprp.fig.1"></graphic>
</listitem>
<listitem>
<para>Click the desired color in the palette.
</para>
<para>The name of the selected color will be displayed after Color Name.</para>
</listitem><listitem><para>Click OK to select the color and dismiss the Color
Chooser.</para>
<para>The selected color will be displayed in the rectangle next to the Background
or Foreground menu and the name of the color will be displayed in the text
field next to the colored rectangle.</para>
</listitem><listitem><para>Repeat the process for Background or Foreground,
if desired.</para>
</listitem><listitem><para>Click Apply in the property editor to apply the
changes.</para>
<para>The background or foreground of the object in the interface will display
the
selected color.</para>
</listitem></orderedlist>
</sect2>
</sect1>
<sect1 id="ABUG.edprp.div.6">
<title id="ABUG.edprp.mkr.6">Example: Editing Main Window Properties</title>
<para>Use the procedure for editing a main window below as an example for
editing
other object types.</para>
<para>Your application might have multiple main windows, but only one <emphasis>primary</emphasis>
main window, which is the starting point for the application. By default,
the
first main window created in the current project is designated as the primary
main window. This designation can be changed in the Application Framework
Editor, described in
<!--Original XRef content: '&xd2;To Establish Application Framework Behavior&xd3;
on
page&numsp;86'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.17">.
</para>
<sect2 id="ABUG.edprp.div.7" role="Procedure">
<title>To Edit Properties of a Main Window<indexterm><primary>windows</primary><secondary>primary</secondary></indexterm><indexterm><primary>windows</primary><secondary>main</secondary></indexterm></title>
<para>Once you have dropped a main window on the workspace do the following
to edit its properties. See
<!--Original XRef content: 'Appendix&numsp;B, &xd2;Revolving Property Editor'--><xref
role="AppendixNumAndTitle" linkend="ABUG.apRPE.mkr.1">, for
descriptions of each of the elements of the property editor.<indexterm><primary>main window</primary><secondary>editing properties of &lt;$startrange></secondary></indexterm><indexterm><primary>primary main window</primary><secondary>editing properties
of &lt;$startrange></secondary></indexterm>
</para>
<orderedlist><listitem><para>Double-click the main window to display the Revolving
Property Editor.</para>
<para><emphasis>Or</emphasis>, Choose Properties from the Editors menu of
the App Builder primary
window, choose Main Window from the Object Type menu, and select the
main window in the Objects list.</para>
<para>The main window will be selected in the Revolving Property Editor.</para>
</listitem><listitem><para>Change the Object Name, if necessary.</para>
</listitem><listitem><para>Change the Window Title to something appropriate.
</para>
<para>This is the label that appears in the title bar of the main window.<indexterm><primary>windows</primary><secondary>naming</secondary></indexterm><indexterm><primary>naming</primary><secondary>windows</secondary></indexterm>
</para>
</listitem><listitem><para>Type the names of an Icon File, an Icon Mask File,
and an Icon Label, if you
want an icon to represent the window when it is minimized.</para>
<para>The Icon File and Icon Mask File must be <command>xpm</command> or <command>xbm</command> graphics files.</para>
</listitem><listitem><para>Change the User Resize Mode, if appropriate.<indexterm><primary>User Resize Mode</primary></indexterm>
</para>
<para>This determines if a user can resize the window in the compiled application.
</para>
</listitem><listitem><para>Select Menubar, Toolbar, and Footer, as appropriate,
to add these functional
areas to the window.</para>
<para>If you select Menubar, you will want to create menus after you finish
editing
main window properties. See
<!--Original XRef content: '&xd2;Creating and Editing Menus&xd3; on page&numsp;45'--><xref
role="SecTitleAndPageNum" linkend="ABUG.crobj.mkr.11"> for
instructions.</para>
<note>
<para>Selecting Menubar is the same as dragging a menu bar from the
Controls palette and dropping it on a main window.</para>
</note>
<para>If you select Toolbar or Footer, you will want to edit the properties
of the
control panes that comprise these objects after you finish editing main
window properties. You can drop controls on the control panes, make
connections to programmatic actions, and do other things that can be done
to any control pane.
</para>
</listitem>
<listitem><para>Change the Size Policy and Size, as appropriate.
</para>
<note>
<para>For all main windows and custom dialogs you will probably want to
leave the Size Policy as Fixed while you are creating the application, and
change it to Fit Contents as you finish the application, for internationalization
and other purposes. When Size Policy is Fit Contents, the window will change
size to accommodate changes in the size of objects as the text in the objects
changes&mdash;or if the font size changes, for example.<indexterm><primary>Size Policy property</primary></indexterm>
</para>
</note>
</listitem>
<listitem><para>Set Initial State to Iconic if you want the application to
appear as an icon
when it is started.<indexterm><primary>Initial State property</primary><secondary>Iconic</secondary>
</indexterm>
</para>
</listitem>
<listitem><para>If you want the main window to be invisible when
the application is started,
deselect the visible setting for Initial State.</para>
<para>If the Visible check box is checked, click it to deselect it.<indexterm><primary>Initial State property</primary><secondary>Visible</secondary>
</indexterm>
</para>
</listitem>
<listitem>
<para>Set Background and Foreground colors, if appropriate.
</para>
<para>Type in a color name if you know it or press mouse button 1 on the
Background or Foreground menu button and choose Color Chooser to
display the Color Chooser. Select a color and click OK. Background sets the
color of the blank pane area of the window. Foreground does nothing that is
visible in the completed interface.</para>
</listitem>
<listitem>
<para>Click Help Text to add on item help, if 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.</para>
</listitem><listitem><para>Click OK to apply the changes and dismiss the Revolving
Property Editor.</para>
<para>Unless you are creating a primary main window, you are finished with
this
task.</para>
</listitem>
<listitem>
<para>If you are creating a primary main window, choose
Application Framework
Editor from the Editors menu.</para>
</listitem>
<listitem>
<para>Type a Vendor Name and Version number in the Application
section of the
Application Framework Editor, if appropriate.</para>
<para>See
<!--Original XRef content: '&xd2;To Establish Application Framework Behavior&xd3;
on page&numsp;86'--><xref role="SecTitleAndPageNum" linkend="ABUG.afunc.mkr.17">
for details
about the editor.</para>
</listitem>
<listitem>
<para>Click OK in the Application Framework Editor to
apply the changes and
close the editor.<indexterm><primary>main window</primary><secondary>editing properties of &lt;$endrange></secondary></indexterm><indexterm><primary>primary main window</primary><secondary>editing properties of &lt;$endrange></secondary></indexterm>
</para>
</listitem></orderedlist>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:11:44-->