1<sect1 id="Grip_Widget">
2<title>Grip Widget</title>
3<!-- .XS -->
4<!-- 	Grip Widget -->
5<!-- .XE -->
6<indexterm significance="preferred"><primary>Grip widget</primary></indexterm>
7<literallayout class="monospaced">
8<!-- .TA 2.0i -->
9<!-- .ta 2.0i -->
10<!-- .sp -->
11Application header file	&lt;X11/Xaw/Grip.h&gt;
12<indexterm><primary>Grip.h</primary></indexterm>
13Class header file	&lt;X11/Xaw/GripP.h&gt;
14<indexterm><primary>GripP.h</primary></indexterm>
15Class	gripWidgetClass
16<indexterm><primary>gripWidgetClass</primary></indexterm>
17Class Name	Grip
18<indexterm><primary>Grip widget</primary><secondary>class name</secondary></indexterm>
19Superclass	Simple
20<!-- .sp -->
21</literallayout>
22<para>
23<!-- .LP -->
24The Grip widget provides a small rectangular region in which user input
25events (such as ButtonPress or ButtonRelease) may be handled.  The most
26common use for the Grip widget is as an attachment point for visually
27repositioning an object, such as the pane border in a Paned widget.
28</para>
29<sect2 id='Grip::Resources'>
30<title>Resources</title>
31<para>
32<!-- .LP -->
33When creating a Grip widget instance, the following resources are
34retrieved from the argument list or from the resource database:
35</para>
36<para>
37<!-- .LP -->
38<indexterm><primary>Grip widget</primary><secondary>resources</secondary></indexterm>
39<informaltable>
40  <tgroup cols='5' align='center'>
41  <colspec colname='c1'/>
42  <colspec colname='c2'/>
43  <colspec colname='c3'/>
44  <colspec colname='c4'/>
45  <colspec colname='c5'/>
46  <thead>
47    <row>
48      <entry>Name</entry>
49      <entry>Class</entry>
50      <entry>Type</entry>
51      <entry>Notes</entry>
52      <entry>Default Value</entry>
53    </row>
54  </thead>
55  <tbody>
56    <row>
57      <entry>accelerators</entry>
58      <entry>Accelerators</entry>
59      <entry>AcceleratorTable</entry>
60      <entry></entry>
61      <entry>NULL</entry>
62    </row>
63    <row>
64      <entry>ancestorSensitive</entry>
65      <entry>AncestorSensitive</entry>
66      <entry>Boolean</entry>
67      <entry>D</entry>
68      <entry>True</entry>
69    </row>
70    <row>
71      <entry>background</entry>
72      <entry>Background</entry>
73      <entry>Pixel</entry>
74      <entry></entry>
75      <entry>XtDefaultBackground</entry>
76    </row>
77    <row>
78      <entry>backgroundPixmap</entry>
79      <entry>Pixmap</entry>
80      <entry>Pixmap</entry>
81      <entry></entry>
82      <entry>XtUnspecifiedPixmap</entry>
83    </row>
84    <row>
85      <entry>borderColor</entry>
86      <entry>BorderColor</entry>
87      <entry>Pixel</entry>
88      <entry></entry>
89      <entry>XtDefaultForeground</entry>
90    </row>
91    <row>
92      <entry>borderPixmap</entry>
93      <entry>Pixmap</entry>
94      <entry>Pixmap</entry>
95      <entry></entry>
96      <entry>XtUnspecifiedPixmap</entry>
97    </row>
98    <row>
99      <entry>borderWidth</entry>
100      <entry>BorderWidth</entry>
101      <entry>Dimension</entry>
102      <entry></entry>
103      <entry>0</entry>
104    </row>
105    <row>
106      <entry>callback</entry>
107      <entry>Callback</entry>
108      <entry>Callback</entry>
109      <entry></entry>
110      <entry>NULL</entry>
111    </row>
112    <row>
113      <entry>colormap</entry>
114      <entry>Colormap</entry>
115      <entry>Colormap</entry>
116      <entry></entry>
117      <entry>Parent's Colormap</entry>
118    </row>
119    <row>
120      <entry>cursor</entry>
121      <entry>Cursor</entry>
122      <entry>Cursor</entry>
123      <entry></entry>
124      <entry>None</entry>
125    </row>
126    <row>
127      <entry>cursorName</entry>
128      <entry>Cursor</entry>
129      <entry>String</entry>
130      <entry></entry>
131      <entry>NULL</entry>
132    </row>
133    <row>
134      <entry>depth</entry>
135      <entry>Depth</entry>
136      <entry>int</entry>
137      <entry>C</entry>
138      <entry>Parent's Depth</entry>
139    </row>
140    <row>
141      <entry>destroyCallback</entry>
142      <entry>Callback</entry>
143      <entry>XtCallbackList</entry>
144      <entry></entry>
145      <entry>NULL</entry>
146    </row>
147    <row>
148      <entry>foreground</entry>
149      <entry>Foreground</entry>
150      <entry>Pixel</entry>
151      <entry></entry>
152      <entry>XtDefaultForeground</entry>
153    </row>
154    <row>
155      <entry>height</entry>
156      <entry>Height</entry>
157      <entry>Dimension</entry>
158      <entry></entry>
159      <entry>8</entry>
160    </row>
161    <row>
162      <entry>insensitiveBorder</entry>
163      <entry>Insensitive</entry>
164      <entry>Pixmap</entry>
165      <entry></entry>
166      <entry>GreyPixmap</entry>
167    </row>
168    <row>
169      <entry>international</entry>
170      <entry>International</entry>
171      <entry>Boolean</entry>
172      <entry>C</entry>
173      <entry>False</entry>
174    </row>
175    <row>
176      <entry>mappedWhenManaged</entry>
177      <entry>MappedWhenManaged</entry>
178      <entry>Boolean</entry>
179      <entry></entry>
180      <entry>True</entry>
181    </row>
182    <row>
183      <entry>pointerColor</entry>
184      <entry>Foreground</entry>
185      <entry>Pixel</entry>
186      <entry></entry>
187      <entry>XtDefaultForeground</entry>
188    </row>
189    <row>
190      <entry>pointerColorBackground</entry>
191      <entry>Background</entry>
192      <entry>Pixel</entry>
193      <entry></entry>
194      <entry>XtDefaultBackground</entry>
195    </row>
196    <row>
197      <entry>screen</entry>
198      <entry>Screen</entry>
199      <entry>Screen</entry>
200      <entry>R</entry>
201      <entry>Parent's Screen</entry>
202    </row>
203    <row>
204      <entry>sensitive</entry>
205      <entry>Sensitive</entry>
206      <entry>Boolean</entry>
207      <entry></entry>
208      <entry>True</entry>
209    </row>
210    <row>
211      <entry>translations</entry>
212      <entry>Translations</entry>
213      <entry>TranslationTable</entry>
214      <entry></entry>
215      <entry>NULL</entry>
216    </row>
217    <row>
218      <entry>width</entry>
219      <entry>Width</entry>
220      <entry>Dimension</entry>
221      <entry></entry>
222      <entry>8</entry>
223    </row>
224    <row>
225      <entry>x</entry>
226      <entry>Position</entry>
227      <entry>Position</entry>
228      <entry></entry>
229      <entry>0</entry>
230    </row>
231    <row>
232      <entry>y</entry>
233      <entry>Position</entry>
234      <entry>Position</entry>
235      <entry></entry>
236      <entry>0</entry>
237    </row>
238  </tbody>
239  </tgroup>
240</informaltable>
241<!-- .Ac -->
242<!-- .As -->
243<!-- .Bg -->
244<!-- .Gp -->
245<!-- .Bc -->
246<!-- .Bp -->
247<!-- .Bw -->
248<variablelist>
249  <varlistentry>
250    <term>
251      <function>callback</function>
252    </term>
253    <listitem>
254      <para>
255All routines on this list are called whenever the <function>GripAction</function>
256action routine is invoked.  The <emphasis remap='I'>call_data</emphasis> contains all
257information passed to the action routine.  A detailed description
258is given below in the <function>Grip Actions</function> section.
259<!-- .Cm -->
260<!-- .Cu -->
261<!-- .Cn -->
262<!-- .Dp -->
263<!-- .Dc -->
264      </para>
265    </listitem>
266  </varlistentry>
267  <varlistentry>
268    <term>
269      <function>foreground</function>
270    </term>
271    <listitem>
272      <para>
273A pixel value which indexes the widget's colormap to derive the color
274used to flood fill the entire Grip widget.
275<!-- .Hw -->
276<!-- .Ib -->
277<!-- .Ix -->
278<!-- .Mm -->
279<!-- .Pf -->
280<!-- .Pb -->
281<!-- .Sc -->
282<!-- .Se -->
283<!-- .Tr -->
284<!-- .Xy -->
285    </para>
286  </listitem>
287  </varlistentry>
288</variablelist>
289</para>
290</sect2>
291<sect2 id="Grip_Actions">
292<title>Grip Actions</title>
293<indexterm><primary>Grip widget</primary><secondary>actions</secondary></indexterm>
294<para>
295<!-- .LP -->
296The Grip widget does not declare any default event translation bindings,
297but it does declare a single action routine named <function>GripAction</function>.  The
298<indexterm><primary>Grip widget</primary><secondary>GripAction routine</secondary></indexterm>
299client specifies an arbitrary event translation table, optionally giving
300parameters to the <function>GripAction</function> routine.
301</para>
302<para>
303<!-- .LP -->
304The <function>GripAction</function> routine executes the callbacks on the
305<function>callback</function> list, passing as <function>call_data</function> a pointer to a
306<function>XawGripCallData</function> structure, defined in the Grip widget's application
307header file.
308</para>
309<para>
310<!-- .LP -->
311<literallayout class="monospaced">
312<!-- .TA .5i 2.25i -->
313<!-- .ta .5i 2.25i -->
314<indexterm significance="preferred"><primary>XawGripCallData</primary></indexterm>
315<indexterm significance="preferred"><primary>XawGripCallDataRec</primary></indexterm>
316<!-- .sp -->
317typedef struct _XawGripCallData {
318	XEvent *event;
319	String *params;
320	Cardinal num_params;
321} XawGripCallDataRec, *XawGripCallData,
322  GripCallDataRec, *GripCallData; /* supported for R4 compatibility */
323<indexterm><primary>XawGripCallDataRec</primary></indexterm>
324<indexterm><primary>XawGripCallData</primary></indexterm>
325<indexterm><primary>GripCallData</primary></indexterm>
326<!-- .sp -->
327</literallayout>
328</para>
329<para>
330<!-- .LP -->
331In this structure, the <emphasis remap='I'>event</emphasis> is a pointer to the input event that
332triggered the action.  <emphasis remap='I'>params</emphasis> and <emphasis remap='I'>num_params</emphasis> give the string
333parameters specified in the translation table for the particular event
334binding.
335<indexterm><primary>Grip widget</primary><secondary>GripAction table</secondary></indexterm>
336</para>
337<para>
338<!-- .LP -->
339The following is an example of a translation table that uses the GripAction:
340</para>
341<para>
342<!-- .LP -->
343<literallayout class="monospaced">
344<!-- .TA .5i 2.5i -->
345<!-- .ta .5i 2.5i -->
346<!-- .sp -->
347	&lt;Btn1Down&gt;:	GripAction(press)
348	&lt;Btn1Motion&gt;:	GripAction(move)
349	&lt;Btn1Up&gt;:	GripAction(release)
350<!-- .sp -->
351</literallayout>
352For a complete description of the format of translation tables, see the
353<olink targetdoc='intrinsics' targetptr='Translation_Management'
354><citetitle>X Toolkit Intrinsics - C Language Interface</citetitle></olink>.
355
356</para>
357</sect2>
358</sect1>
359