aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/Dialog.xml
diff options
context:
space:
mode:
Diffstat (limited to 'libXaw/specs/Dialog.xml')
-rw-r--r--libXaw/specs/Dialog.xml692
1 files changed, 692 insertions, 0 deletions
diff --git a/libXaw/specs/Dialog.xml b/libXaw/specs/Dialog.xml
new file mode 100644
index 000000000..f77006c6a
--- /dev/null
+++ b/libXaw/specs/Dialog.xml
@@ -0,0 +1,692 @@
+<sect1 id="Dialog_Widget">
+<title>Dialog Widget</title>
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Dialog Widget -->
+<!-- .XE -->
+<!-- .IN "Dialog widget" "" "@DEF@" -->
+<literallayout class="monospaced">
+<!-- .TA 2.0i -->
+<!-- .ta 2.0i -->
+<!-- .sp -->
+Application Header file &lt;X11/Xaw/Dialog.h&gt;
+<!-- .IN "Dialog.h" "" -->
+Class Header file &lt;X11/Xaw/DialogP.h&gt;
+<!-- .IN "DialogP.h" "" -->
+Class dialogWidgetClass
+<!-- .IN "dialogWidgetClass" "" -->
+Class Name Dialog
+<!-- .IN "Dialog widget" "class name" -->
+Superclass Form
+<!-- .sp -->
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The Dialog widget implements a commonly used interaction semantic to
+prompt for auxiliary input from a user. For example, you can use a
+Dialog widget when an application requires a small piece of information,
+such as a filename, from the user. A Dialog widget, which is simply a
+special case of the Form widget, provides a convenient way to create a
+preconfigured form.
+</para>
+<para>
+<!-- .LP -->
+The typical Dialog widget contains three areas. The first line
+contains a description of the function of the Dialog widget, for
+example, the string <emphasis remap='I'>Filename:</emphasis>. The second line contains an area
+into which the user types input. The third line can contain buttons
+that let the user confirm or cancel the Dialog input. Any of these
+areas may be omitted by the application.
+</para>
+<sect2 id="dialog_resources">
+<title>Resources</title>
+<para>
+<!-- .LP -->
+When creating a Dialog widget instance, the following resources are
+retrieved from the argument list or the resource database:
+<!-- .IN "Dialog widget" "resources" -->
+<informaltable>
+ <tgroup cols='5' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Notes</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>accelerators</entry>
+ <entry>Accelerators</entry>
+ <entry>AcceleratorTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>ancestorSensitive</entry>
+ <entry>AncestorSensitive</entry>
+ <entry>Boolean</entry>
+ <entry>D</entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>background</entry>
+ <entry>Background</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultBackground</entry>
+ </row>
+ <row>
+ <entry>backgroundPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderColor</entry>
+ <entry>BorderColor</entry>
+ <entry>Pixel</entry>
+ <entry></entry>
+ <entry>XtDefaultForeground</entry>
+ </row>
+ <row>
+ <entry>borderPixmap</entry>
+ <entry>Pixmap</entry>
+ <entry>Pixmap</entry>
+ <entry></entry>
+ <entry>XtUnspecifiedPixmap</entry>
+ </row>
+ <row>
+ <entry>borderWidth</entry>
+ <entry>BorderWidth</entry>
+ <entry>Dimension</entry>
+ <entry></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>ReadOnly</entry>
+ <entry>WidgetList</entry>
+ <entry>R</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Colormap</entry>
+ <entry>Colormap</entry>
+ <entry></entry>
+ <entry>Parent's Colormap</entry>
+ </row>
+ <row>
+ <entry>defaultDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Depth</entry>
+ <entry>int</entry>
+ <entry>C</entry>
+ <entry>Parent's Depth</entry>
+ </row>
+ <row>
+ <entry>destroyCallback</entry>
+ <entry>Callback</entry>
+ <entry>XtCallbackList</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>Height</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>icon</entry>
+ <entry>Icon</entry>
+ <entry>Bitmap</entry>
+ <entry></entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>label</entry>
+ <entry>Label</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>"label"</entry>
+ </row>
+ <row>
+ <entry>mappedWhenManaged</entry>
+ <entry>MappedWhenManaged</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>numChildren</entry>
+ <entry>ReadOnly</entry>
+ <entry>Cardinal</entry>
+ <entry>R</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Screen</entry>
+ <entry>Screen</entry>
+ <entry>R</entry>
+ <entry>Parent's Screen</entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry>Sensitive</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>True</entry>
+ </row>
+ <row>
+ <entry>translations</entry>
+ <entry>Translations</entry>
+ <entry>TranslationTable</entry>
+ <entry></entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>Value</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry>no value widget</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>Width</entry>
+ <entry>Dimension</entry>
+ <entry>A</entry>
+ <entry>Enough space to contain all children</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>Position</entry>
+ <entry>Position</entry>
+ <entry></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<!-- .Ac -->
+<!-- .As -->
+<!-- .Bg -->
+<!-- .Gp -->
+<!-- .Bc -->
+<!-- .Bp -->
+<!-- .Bw -->
+<!-- .Ch -->
+<!-- .Cm -->
+<!-- .Dd -->
+<!-- .Dp -->
+<!-- .Dc -->
+<!-- .Hw -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <function>icon</function>
+ </term>
+ <listitem>
+ <para>
+A pixmap image to be displayed immediately to the left of the
+Dialog widget's label.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>label</function>
+ </term>
+ <listitem>
+ <para>
+A string to be displayed at the top of the Dialog widget.
+<!-- .Mm -->
+<!-- .Nc -->
+<!-- .Sc -->
+<!-- .Se -->
+<!-- .Tr -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <function>value</function>
+ </term>
+ <listitem>
+ <para>
+An initial value for the string field that the user will enter text
+into. By default, no text entry field is available to the user.
+Specifying an initial value for <function>value</function> activates the text entry
+field. If string input is desired, but no initial value is to be
+specified then set this resource to "" (empty string).
+<!-- .Xy -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+</sect2>
+<sect2 id="Constraint_Resources">
+<title>Constraint Resources</title>
+<para>
+<!-- .LP -->
+<!-- .IN "Dialog widget" "constraint resources" -->
+Each child of the Dialog widget may request special layout resources
+be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Dialog
+widget's children to specify individual layout requirements.
+</para>
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='5' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <colspec colname='c5'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Type</entry>
+ <entry>Notes</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>bottom</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>fromHoriz</entry>
+ <entry>Widget</entry>
+ <entry>Widget</entry>
+ <entry></entry>
+ <entry>NULL (left edge of Dialog)</entry>
+ </row>
+ <row>
+ <entry>fromVert</entry>
+ <entry>Widget</entry>
+ <entry>Widget </entry>
+ <entry></entry>
+ <entry>NULL (top edge of Dialog)</entry>
+ </row>
+ <row>
+ <entry>horizDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ <row>
+ <entry>left</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>resizable</entry>
+ <entry>Boolean</entry>
+ <entry>Boolean</entry>
+ <entry></entry>
+ <entry>FALSE</entry>
+ </row>
+ <row>
+ <entry>right</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>top</entry>
+ <entry>Edge</entry>
+ <entry>XawEdgeType</entry>
+ <entry></entry>
+ <entry>XawRubber</entry>
+ </row>
+ <row>
+ <entry>vertDistance</entry>
+ <entry>Thickness</entry>
+ <entry>int</entry>
+ <entry></entry>
+ <entry><function>defaultDistance</function> resource</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<literallayout class="monospaced">
+bottom
+left
+right
+top What to do with this edge of the child when
+ the parent is resized. This resource may be
+ any edgeType. See Layout Semantics for
+ details.
+
+fromHoriz
+fromVert Which widget this child should be placed
+ underneath (or to the right of). If a value
+ of NULL is specified then this widget will be
+ positioned relative to the edge of the par-
+ ent.
+
+horizDistance
+vertDistance The amount of space, in pixels, between this
+ child and its left or upper neighbor.
+
+resizable If this resource is False then the parent
+ widget will ignore all geometry request made
+ by this child. The parent may still resize
+ this child itself, however.
+</literallayout>
+<!-- .Bt -->
+<!-- .Fh -->
+<!-- .Hd -->
+<!-- .Rl -->
+</para>
+</sect2>
+<sect2 id="dialog_layout_semantics">
+<title>Layout Semantics</title>
+<!-- .IN "Dialog widget" "layout semantics" -->
+<para>
+The Dialog widget uses two different sets of layout seman-
+tics. One is used when initially laying out the children.
+The other is used when the Dialog is resized.
+</para>
+<para>
+The first layout method uses the <function>fromVert</function> mand <function>fromHoriz</function>
+resources to place the children of the Dialog. A single
+pass is made through the Dialog widget's children in the
+order that they were created. Each child is then placed in
+the Dialog widget below or to the right of the widget speci-
+fied by the <function>fromVert</function> mand <function>fromHoriz</function> mresources. The distance
+the new child is placed from its left or upper neighbor is
+determined by the <function>horizDistance</function> mand <function>vertDistance</function> mresources.
+This implies some things about how the order of creation
+affects the possible placement of the children. The Form
+widget registers a string to widget converter which does not
+postpone conversion and does not cache conversion results.
+</para>
+<para>
+
+The second layout method is used when the Dialog is resized.
+It does not matter what causes this resize, and it is possi-
+ble for a resize to happen before the widget becomes visible
+(due to constraints imposed by the parent of the Dialog).
+This layout method uses the <function>bottom</function> ,
+<function>top</function> , <function>left</function> , and
+<function>right</function>
+resources. These resources are used to determine what will
+happen to each edge of the child when the Dialog is resized.
+If a value of <function>XawChain</function>
+<emphasis remap='I'>&lt;something&gt;</emphasis>
+ is specified, the the edge
+of the child will remain a fixed distance from the <emphasis remap='I'>chain</emphasis>
+edge of the Dialog. For example if <function>XawChainLeft</function>
+mis specified for the <function>right</function> mresource of a child
+then the right edge
+of that child will remain a fixed distance from the left
+edge of the Dialog widget. If a value of <function>XawRubber</function> mis spec-
+ified, that edge will grow by the same percentage that the
+Dialog grew. For instance if the Dialog grows by 50% the
+left edge of the child (if specified as <function>XawRubber</function> mwill be
+50% farther from the left edge of the Dialog). One must be
+very careful when specifying these resources, for when they
+are specified incorrectly children may overlap or completely
+occlude other children when the Dialog widget is resized.
+</para>
+
+<para>
+<!-- .LP -->
+<informaltable>
+ <tgroup cols='3' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <thead>
+ <row>
+ <entry>Edge Type</entry>
+ <entry>Resource Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XawChainBottom</entry>
+ <entry>ChainBottom</entry>
+ <entry>Edge remains a fixed distance from bottom of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainLeft</entry>
+ <entry>ChainLeft</entry>
+ <entry>Edge remains a fixed distance from left of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainRight</entry>
+ <entry>ChainRight</entry>
+ <entry>Edge remains a fixed distance from right of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawChainTop</entry>
+ <entry>ChainTop</entry>
+ <entry>Edge remains a fixed distance from top of Dialog</entry>
+ </row>
+ <row>
+ <entry>XawRubber</entry>
+ <entry>Rubber</entry>
+ <entry>Edges will move a proportional distance</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<sect3 id="Example">
+<title>Example</title>
+<para>
+<!-- .LP -->
+If you wish to force the Dialog to never resize one or more of its children
+then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and
+<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause
+the child to remain a fixed distance from the top and left
+edges of the Dialog, and to never resize.
+</para>
+</sect3>
+<sect3 id="Special_Considerations">
+<title>Special Considerations</title>
+<!-- .IN "Dialog widget" "special considerations" -->
+<para>
+<!-- .LP -->
+The Dialog widget automatically sets the <function>top</function> and <function>bottom</function>
+resources for all Children that are subclasses of the Command widget,
+as well as the widget children that are used to contain the <function>label</function>,
+<function>value</function>, and <function>icon</function>. This policy allows the buttons at the
+bottom of the Dialog to interact correctly with the predefined children,
+and makes it possible for a client to simply create and manage a new
+Command button without having to specify its constraints.
+</para>
+<para>
+<!-- .LP -->
+The Dialog will also set <function>fromLeft</function> to the last button in the
+<!-- .IN "fromLeft" "" -->
+Dialog for each new button added to the Dialog widget.
+</para>
+<para>
+<!-- .LP -->
+The automatically added constraints cannot be overridden, as they are
+policy decisions of the Dialog widget. If a more flexible Dialog is
+desired, the application is free to use the Form widget to create its
+own Dialog policy.
+</para>
+</sect3>
+</sect2>
+<sect2 id="Automatically_Created_Children_">
+<title>Automatically Created Children.</title>
+<!-- .IN "Dialog widget" "automatically created children" -->
+<para>
+<!-- .LP -->
+The Dialog uses Label widgets to contain the <function>label</function> and <function>icon</function>.
+These widgets are named <emphasis remap='I'>label</emphasis> and <emphasis remap='I'>icon</emphasis> respectively. The
+Dialog <function>value</function> is contained in an AsciiText widget whose name is
+<function>value</function>. Using <function>XtNameToWidget</function> the application can change
+<!-- .IN "XtNameToWidget" "" -->
+those resources associated with each of these widgets that are not
+available through the Dialog widget itself.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+<sect2 id="dialog_convenience_routines">
+<title>Convenience Routines</title>
+<para>
+<!-- .LP -->
+To return the character string in the text field, use
+<!-- .PN XawDialogGetValueString . -->
+<!-- .IN "XawDialogGetValueString" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>String<function> XawDialogGetValueString</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Dialog widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function returns a copy of the value string of the Dialog
+widget. This string is allocated by the AsciiText widget and will
+remain valid and unchanged until another call to
+<function>XawDialogGetValueString</function> or an <function>XtGetValues</function> call on the
+<function>value</function> widget, when the string will be automatically freed, and
+a new string is returned. This string may be freed earlier by calling
+the function <function>XawAsciiSourceFreeString</function>.
+<!-- .IN "XawAsciiSourceFreeString" "" -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a new button to the Dialog widget use
+<function>XawDialogAddButton</function>.
+<!-- .IN "XawDialogAddButton" "" "@DEF@" -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XawDialogAddButton</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>String<parameter> name</parameter></paramdef>
+ <paramdef>XtCallbackProc<parameter> func</parameter></paramdef>
+ <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Dialog widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the new Command button to be added to the Dialog.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>func</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a callback function to be called when this button is activated. If
+NULL is specified then no callback is added.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client_data to be passed to the <emphasis remap='I'>func</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+This function is merely a shorthand for the code sequence:
+<!-- .sp -->
+<literallayout class="monospaced">
+<!-- .SM -->
+<!-- .TA 1i 2i -->
+<!-- .ta 1i 2i -->
+{
+ Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
+ XtAddCallback(button, XtNcallback, func, client_data);
+}
+<!-- .NL -->
+</literallayout>
+<!-- .sp -->
+
+</para>
+</sect2>
+</sect1>