man/XtPopup.man

   1 .\" Copyright 1993 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be
  12 .\" included in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  15 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .ds tk X Toolkit
  28 .ds xT X Toolkit Intrinsics \- C Language Interface
  29 .ds xI Intrinsics
  30 .ds xW X Toolkit Athena Widgets \- C Language Interface
  31 .ds xL Xlib \- C Language X Interface
  32 .ds xC Inter-Client Communication Conventions Manual
  33 .ds Rn 3
  34 .ds Vn 2.2
  35 .hw XtPopup-Spring-Loaded XtCallback-None XtCallback-Nonexclusive XtCallback-Exclusive wid-get
  36 .na
  37 .de Ds
  38 .nf
  39 .\\$1D \\$2 \\$1
  40 .ft CW
  41 .ps \\n(PS
  42 .\".if \\n(VS>=40 .vs \\n(VSu
  43 .\".if \\n(VS<=39 .vs \\n(VSp
  44 ..
  45 .de De
  46 .ce 0
  47 .if \\n(BD .DF
  48 .nr BD 0
  49 .in \\n(OIu
  50 .if \\n(TM .ls 2
  51 .sp \\n(DDu
  52 .fi
  53 ..
  54 .de IN          \" send an index entry to the stderr
  55 ..
  56 .de Pn
  57 .ie t \\$1\fB\^\\$2\^\fR\\$3
  58 .el \\$1\fI\^\\$2\^\fP\\$3
  59 ..
  60 .de ZN
  61 .ie t \fB\^\\$1\^\fR\\$2
  62 .el \fI\^\\$1\^\fP\\$2
  63 ..
  64 .ny0
  65 .TH XtPopup __libmansuffix__ __xorgversion__ "XT FUNCTIONS"
  66 .SH NAME
  67 XtPopup, XtPopupSpringLoaded, XtCallbackNone, XtCallbackNonexclusive, XtCallbackExclusive \- map a pop-up
  68 .SH SYNTAX
  69 .HP
  70 void XtPopup(Widget \fIpopup_shell\fP, XtGrabKind \fIgrab_kind\fP);
  71 .HP
  72 void XtPopupSpringLoaded(Widget \fIpopup_shell\fP);
  73 .HP
  74 void XtCallbackNone(Widget \fIw\fP, XtPointer \fIclient_data\fP, XtPointer
  75 \fIcall_data\fP):
  76 .HP
  77 void XtCallbackNonexclusive(Widget \fIw\fP, XtPointer \fIclient_data\fP,
  78 XtPointer \fIcall_data\fP);
  79 .HP
  80 void XtCallbackExclusive(Widget \fIw\fP, XtPointer \fIclient_data\fP,
  81 XtPointer \fIcall_data\fP);
  82 .HP
  83 void MenuPopup(String \fIshell_name\fP);
  84 .SH ARGUMENTS
  85 .IP \fIcall_data\fP 1i
  86 Specifies the callback data,
  87 which is not used by this procedure.
  88 .IP \fIclient_data\fP 1i
  89 Specifies the pop-up shell.
  90 .IP \fIgrab_kind\fP 1i
  91 Specifies the way in which user events should be constrained.
  92 .IP \fIpopup_shell\fP 1i
  93 Specifies the widget shell\*(Ps.
  94 .IP \fIw\fP 1i
  95 Specifies the widget.
  96 .SH DESCRIPTION
  97 The
  98 .ZN XtPopup
  99 function performs the following:
 100 .IP \(bu 5
 101 Calls
 102 .ZN XtCheckSubclass
 103 .\".ZN XtCheckSubclass(popup_shell, popupShellWidgetClass)
 104 to ensure popup_shell is a subclass of
 105 .ZN Shell .
 106 .IP \(bu 5
 107 Generates an error if the shell's popped_up field is already
 108 .ZN True .
 109 .IP \(bu 5
 110 Calls the callback procedures on the shell's popup_callback list.
 111 .IP \(bu 5
 112 Sets the shell popped_up field to
 113 .ZN True ,
 114 the shell spring_loaded field to
 115 .ZN False ,
 116 and the shell grab_kind field from grab_kind.
 117 .IP \(bu 5
 118 If the shell's create_popup_child field is non-NULL,
 119 .ZN XtPopup
 120 calls it with popup_shell as the parameter.
 121 .IP \(bu 5
 122 If grab_kind is either
 123 .ZN XtGrabNonexclusive
 124 or
 125 .ZN XtGrabExclusive ,
 126 it calls:
 127 .LP
 128 .Ds
 129 XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False)
 130 .De
 131 .IP \(bu 5
 132 Calls
 133 .ZN XtRealizeWidget
 134 with popup_shell specified.
 135 .IP \(bu 5
 136 Calls
 137 .ZN XMapWindow
 138 with popup_shell specified.
 139 .LP
 140 The
 141 .ZN XtPopupSpringLoaded
 142 function performs exactly as
 143 .ZN XtPopup
 144 except that it sets the shell \fIspring_loaded\fP field to
 145 .ZN True
 146 and always calls
 147 .ZN XtAddGrab
 148 with \fIexclusive\fP
 149 .ZN True
 150 and \fIspring_loaded\fP
 151 .ZN True .
 152 .LP
 153 The
 154 .ZN XtCallbackNone ,
 155 .ZN XtCallbackNonexclusive ,
 156 and
 157 .ZN XtCallbackExclusive
 158 functions call
 159 .ZN XtPopup
 160 with the shell specified by the client data argument
 161 and grab_kind set as the name specifies.
 162 .ZN XtCallbackNone ,
 163 .ZN XtCallbackNonexclusive ,
 164 and
 165 .ZN XtCallbackExclusive
 166 specify
 167 .ZN XtGrabNone ,
 168 .ZN XtGrabNonexclusive ,
 169 and
 170 .ZN XtGrabExclusive ,
 171 respectively.
 172 Each function then sets the widget that executed the callback list
 173 to be insensitive by using
 174 .ZN XtSetSensitive .
 175 Using these functions in callbacks is not required.
 176 In particular,
 177 an application must provide customized code for
 178 callbacks that create pop-up shells dynamically or that must do more than
 179 desensitizing the button.
 180 .LP
 181 .ZN MenuPopup
 182 is known to the translation manager,
 183 which must perform special actions for spring-loaded pop-ups.
 184 Calls to
 185 .ZN MenuPopup
 186 in a translation specification are mapped into calls to a
 187 nonexported action procedure,
 188 and the translation manager fills in parameters
 189 based on the event specified on the left-hand side of a translation.
 190 .LP
 191 If
 192 .ZN MenuPopup
 193 is invoked on
 194 .ZN ButtonPress
 195 (possibly with modifiers),
 196 the translation manager pops up the shell with grab_kind set to
 197 .ZN XtGrabExclusive
 198 and spring_loaded set to
 199 .ZN True .
 200 If
 201 .ZN MenuPopup
 202 is invoked on
 203 .ZN EnterWindow
 204 (possibly with modifiers),
 205 the translation manager pops up the shell with grab_kind set to
 206 .ZN XtGrabNonexclusive
 207 and spring_loaded set to
 208 .ZN False .
 209 Otherwise, the translation manager generates an error.
 210 When the widget is popped up,
 211 the following actions occur:
 212 .IP \(bu 5
 213 Calls
 214 .ZN XtCheckSubclass
 215 .\".ZN XtCheckSubclass(popup_shell, popupShellWidgetClass)
 216 to ensure popup_shell is a subclass of
 217 .ZN Shell .
 218 .IP \(bu 5
 219 Generates an error if the shell's popped_up field is already
 220 .ZN True .
 221 .IP \(bu 5
 222 Calls the callback procedures on the shell's popup_callback list.
 223 .IP \(bu 5
 224 Sets the shell popped_up field to
 225 .ZN True
 226 and the shell grab_kind and spring_loaded fields appropriately.
 227 .IP \(bu 5
 228 If the shell's create_popup_child field is non-NULL,
 229 it is called with popup_shell as the parameter.
 230 .IP \(bu 5
 231 Calls:
 232 .LP
 233 .Ds
 234 XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), spring_loaded)
 235 .De
 236 .IP \(bu 5
 237 Calls
 238 .ZN XtRealizeWidget
 239 with popup_shell specified.
 240 .IP \(bu 5
 241 Calls
 242 .ZN XMapWindow
 243 with popup_shell specified.
 244 .LP
 245 (Note that these actions are the same as those for
 246 .ZN XtPopup .)
 247 .ZN MenuPopup
 248 tries to find the shell by searching the widget tree starting at
 249 the parent of the widget in which it is invoked.
 250 If it finds a shell with the specified name in the pop-up children of
 251 that parent, it pops up the shell with the appropriate parameters.
 252 Otherwise, it moves up the parent chain as needed.
 253 If
 254 .ZN MenuPopup
 255 gets to the application widget and cannot find a matching shell,
 256 it generates an error.
 257 .SH "SEE ALSO"
 258 XtCreatePopupShell(__libmansuffix__),
 259 XtPopdown(__libmansuffix__)
 260 .br
 261 \fI\*(xT\fP
 262 .br
 263 \fI\*(xL\fP