home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / SimpleMenu < prev    next >
Encoding:
Text File  |  1991-07-29  |  10.7 KB  |  322 lines
  1. .NH 2
  2. SimpleMenu Widget
  3. .XS
  4.     SimpleMenu Widget
  5. .XE
  6. .IN "SimpleMenu widget" "" "@DEF@"
  7. .Ds 0
  8. .TA 2.0i
  9. .ta 2.0i
  10. .sp
  11. Application Header file    <X11/Xaw/SimpleMenu.h>
  12. .IN "SimpleMenu.h" ""
  13. Class Header file    <X11/Xaw/SimpleMenP.h>
  14. .IN "SimpleMenP.h" ""
  15. Class        simpleMenuWidgetClass
  16. .IN "simpleMenuWidgetClass" ""
  17. Class Name    SimpleMenu
  18. .IN "SimpleMenu widget" "class name"
  19. Superclass    OverrideShell
  20. .sp
  21. .De
  22. .LP
  23. The SimpleMenu widget is a container for the menu entries.  It is a
  24. direct subclass of shell, and is usually created with
  25. \fBXtCreatePopupShell\fP.  This is the only part of the menu that
  26. actually contains a window.  The SimpleMenu serves as the glue to bind
  27. the individual menu entries together into a menu.
  28. .NH 3
  29. Resources
  30. .LP
  31. .IN "SimpleMenu widget" "resources"
  32. .LP
  33. The resources associated with the SimpleMenu widget control aspects
  34. that will affect the entire menu.  
  35. .ps 9
  36. .nr PS 9
  37. .vs 11
  38. .nr VS 11
  39. .TS H
  40. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  41. _
  42. .sp 3p
  43. .TB
  44. Name    Class    Type    Notes    Default Value
  45. .sp 3p
  46. _
  47. .TH
  48. .R
  49. .sp 3p
  50. accelerators    Accelerators    AcceleratorTable        NULL
  51. ancestorSensitive    AncestorSensitive    Boolean    D    True
  52. allowShellResize    AllowShellResize    Boolean        True
  53. background    Background    Pixel        XtDefaultBackground
  54. backgroundPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  55. backingStore    BackingStore    BackingStore        see below
  56. borderColor    BorderColor    Pixel        XtDefaultForeground
  57. borderPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  58. borderWidth    BorderWidth    Dimension        1
  59. bottomMargin    VerticalMargins    Dimension        0
  60. children    ReadOnly    WidgetList    R    NULL
  61. createPopupChildProc    CreatePopupChildProc    Function        NULL
  62. colormap    Colormap    Colormap        Parent's Colormap
  63. cursor    Cursor    Cursor        None
  64. depth    Depth    int    C    Parent's Depth
  65. destroyCallback    Callback    XtCallbackList        NULL
  66. geometry    Geometry    String        NULL
  67. height    Height    Dimension        Enough space to contain all entries
  68. label    Label    String        NULL
  69. labelClass    LabelClass    Pointer        SmeBSBObjectClass
  70. mappedWhenManaged    MappedWhenManaged    Boolean        True
  71. menuOnScreen    MenuOnScreen    Boolean        True
  72. numChildren    ReadOnly    Cardinal    R    0
  73. overrideRedirect    OverrideRedirect    Boolean        True
  74. popdownCallback    Callback    XtCallbackList        NULL
  75. popupCallback    Callback    XtCallbackList        NULL
  76. popupOnEntry    PopupOnEntry    Widget    A    Label or first entry
  77. rowHeight    RowHeight    Dimension        0
  78. saveUnder    SaveUnder    Boolean        False
  79. screen    Screen    Screen    R    Parent's Screen
  80. sensitive    Sensitive    Boolean        True
  81. topMargin    VerticalMargins    Dimension        0
  82. translations    Translations    TranslationTable        See below
  83. visual    Visual    Visual        CopyFromParent
  84. width    Width    Dimension        Width of widest entry
  85. x    Position    Position        0
  86. y    Position    Position        0
  87. .sp 3p
  88. _
  89. .TE
  90. .ps 11
  91. .nr PS 11
  92. .vs 13
  93. .nr VS 13
  94. .Ac
  95. .As
  96. .IP \fBbackingStore\fP 1.5i
  97. .IN "conversions" "BackingStore"
  98. Determines what type of backing store will be used for the menu.  Legal
  99. values for this resource are \fBNotUseful\fP, \fBWhenMapped\fP, and
  100. \fBAlways\fP.  These values are the backing-store integers defined in
  101. <X11/X.h>.
  102. .Rs "notUseful, whenMapped, always, \fPand\fP default"
  103. If \fBdefault\fP is specified (the default behavior) the server will use
  104. whatever it thinks is appropriate.
  105. .Bg
  106. .Gp
  107. .Bc
  108. .Bp
  109. .Bw
  110. .IP \fBbottomMargin\fP 1.5i
  111. .br
  112. .ns
  113. .IP \fBtopMargin\fP 1.5i
  114. The amount of space between the top or bottom of the menu and the menu entry
  115. closest to that edge.
  116. .Ch
  117. .Cm
  118. .IP \fBcursor\fP 1.5i
  119. The shape of the mouse pointer whenever it is in this widget.
  120. .Dp
  121. .Dc
  122. .IP geometry 1.5i
  123. If this resource is specified it will override the x, y, width and
  124. height of this widget.  The format of this string is
  125. [<\fIwidth\fP>x<\fIheight\fP>][{+ -} <\fIxoffset\fP> {+ -}<\fIyoffset\fP>].
  126. .Hw
  127. .IP \fBlabel\fP 1.5i
  128. This label will be placed at the top of the SimpleMenu, and may not be
  129. highlighted.  The name of the 
  130. label object is \fBmenuLabel\fP.  Using this name it is possible to
  131. modify the label's attributes through the resource database.  When the label
  132. is created, the \fBlabel\fP is hard coded to the value of \fBlabel\fP, and
  133. \fBjustify\fP is hard coded as \fBXtJustifyCenter\fP.
  134. .IP \fBlabelClass\fP 1.5i
  135. Specifies the type of Sme object created as the menu label.
  136. .Mm
  137. .IP \fBmenuOnScreen\fP 1.5i
  138. If the menu is automatically positioned under the cursor with the
  139. \fBXawPositionSimpleMenu\fP action, and this resource is \fBTrue\fP,
  140. then the menu will always be fully visible on the screen.
  141. .Nc
  142. .IP overrideRedirect 1.5i
  143. Determines the value of the override_redirect attribute of the
  144. SimpleMenu's window.  The override_redirect attribute of a window
  145. determines whether or not a window manager may interpose itself between
  146. this window and the root window of the display.  For more information
  147. see the \fIInterclient Communications Conventions Manual\fP.
  148. .IP popdownCallback 1.5i
  149. .br
  150. .ns
  151. .IP popupCallback 1.5i
  152. These callback functions are called by the Xt Intrinsics whenever the
  153. shell is popped up or down (See \fI\*(xT\fP for details).
  154. .IP \fBpopupOnEntry\fP 1.5i
  155. The \fBXawPositionSimpleMenu\fP action will, by default, popup the
  156. SimpleMenu with its label (or first entry) directly under the 
  157. pointer.  To popup the menu under
  158. another entry, set this resource to the menu entry that should be
  159. under the pointer, when the menu is popped up.  This allows the
  160. application to offer the user a default menu entry that can be selected
  161. with out moving the pointer.
  162. .IP \fBrowHeight\fP 1.5i
  163. If this resources is zero (the default) then each menu entry will be
  164. given its desired height.  If this resource has any other value then
  165. all menu entries will be forced to be \fBrowHeight\fP pixels high.
  166. .IP saveUnder 1.5i
  167. If this is \fBTrue\fP then save unders will be active on the menu's window.
  168. .Sc
  169. .Se
  170. .Tr
  171. .Xy
  172. .NH 3
  173. SimpleMenu Actions
  174. .IN "SimpleMenu widget" "actions"
  175. .LP
  176. The SimpleMenu widget supports the following actions:
  177. .IP \(bu 5
  178. Switching the entry under the mouse pointer between 
  179. the foreground and background colors with \fBhighlight\fP
  180. and \fBunhighlight\fP
  181. .IP \(bu 5
  182. Processing menu entry callbacks with \fBnotify\fP
  183. .sp
  184. .LP
  185. .IN "SimpleMenu widget" "default translations"
  186. The following are the default translation bindings used 
  187. by the SimpleMenu widget:
  188. .LP
  189. .sp
  190. .Ds 0
  191. .TA .5i 2.25i
  192. .ta .5i 2.25i
  193.     <EnterWindow>:    highlight(\|)
  194.     <LeaveWindow>:    unhighlight(\|)
  195.     <BtnMotion>:    highlight(\|)
  196.     <BtnUp>:    MenuPopdown(\|) notify(\|) unhighlight(\|)
  197. .De
  198. .sp
  199. .LP
  200. .IN "SimpleMenu widget" "MenuPopdown routine"
  201. The user can pop down the menu without activating any of the callback
  202. functions by releasing the pointer button when no menu item is
  203. highlighted.
  204. .sp
  205. .LP
  206. The full list of actions supported by SimpleMenu is:
  207. .IP \fBhighlight\fP() 1.5i
  208. Highlight the menu entry that is currently under the pointer.
  209. Only a item that is highlighted will be notified when the \fBnotify\fP
  210. action is invoked.  The look of a highlighted entry is determined by
  211. the menu entry. 
  212. .IP \fBunhighlight\fP(\|) 1.5i
  213. Unhighlights the currently highlighted menu item, and returns it to
  214. its normal look.
  215. .IP \fBnotify\fP(\|) 1.5i
  216. Notifies the menu entry that is currently highlighted that is has been
  217. selected.  It is the responsibility of the menu entry to take the
  218. appropriate action.
  219. .IP \fBMenuPopdown\fP(\fImenu\fP)
  220. This action is defined in \fI\*(xT\fP.
  221. .IN "SimpleMenu widget" "MenuPopdown routine"
  222. .NH 3
  223. Positioning the SimpleMenu
  224. .IN "XawPositionSimpleMenu" "" "@DEF@"
  225. .IN "SimpleMenu widget" "positioning" "@DEF@"
  226. .LP
  227. If the SimpleMenu widget is to be used as a pulldown menu then the
  228. MenuButton widget, or some other outside means should be used to place
  229. the menu when it is popped up.
  230. .LP
  231. If popup menus are desired it will be necessary to add the
  232. \fBXawPositionSimpleMenu\fP and \fBMenuPopup\fP actions to the
  233. translation table of the widget that will be popping up the menu.  The
  234. \fBMenuPopup\fP action is described in \fI\*(xT\fP.
  235. \fBXawPositionSimpleMenu\fP is a global action procedure registered by
  236. the SimpleMenu widget when the first one is created or the convenience
  237. routine \fBXawSimpleMenuAddGlobalActions\fP is called.
  238. .LP
  239. Translation writers should be aware that Xt does not register grabs on
  240. ``don't care'' modifiers, and therefore the left hand side of the
  241. production should be written to exclude unspecified modifiers.
  242. For example these are the translations needed to popup some of
  243. \fBxterm's\fP menus: 
  244. .sp
  245. .LP
  246. .Ds 0
  247. .TA .5i 2.25i
  248. .ta .5i 2.25i
  249.     !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
  250.     !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes)
  251. .De
  252. .sp 1
  253. .LP
  254. .IP \fBXawPositionSimpleMenu\fP(\fImenu\fP) 2.25i
  255. The \fBXawPositionSimpleMenu\fP routine will search for the menu name
  256. passed to it using \fBXtNameToWidget\fP starting with the widget
  257. invoking the action as the reference widget.  If it is unsuccessful it
  258. will continue up the widget tree using each of the invoking widget's
  259. ancestors as the reference widget.  If it is still unsuccessful it will
  260. print a warning message and give up.  \fBXawPositionSimpleMenu\fP will
  261. position the menu directly under the pointer cursor.  The menu will be
  262. placed so that the pointer cursor is centered on the entry named by the
  263. \fBpopupOnEntry\fP resource.  If the \fBmenuOnScreen\fP resource is
  264. \fBTrue\fP then the menu will always be fully visible on the screen.
  265. .NH 3
  266. Convenience Routines
  267. .NH 4
  268. Registering the Global Action Routines
  269. .LP
  270. .IN "XawPositionSimpleMenu" ""
  271. The \fBXawPositionSimpleMenu\fP action routine may often be invoked
  272. before any menus have been created.  This can occur when an
  273. application uses dynamic menu creation.  In these cases an application will
  274. need to register this global action routine by calling
  275. \fBXawSimpleMenuAddGlobalActions\fP:
  276. .IN "XawSimpleMenuAddGlobalActions" "" "@DEF@"
  277. .FD 0
  278. void XawSimpleMenuAddGlobalActions(\fIapp_con\fP)
  279. .br
  280.       XtAppContext \fIapp_con\fP;
  281. .FN
  282. .IP \fIapp_con\fP 1i
  283. Specifies the application context in which this action should be registered.
  284. .LP
  285. This function need only be called once per application and must be
  286. called before any widget that uses \fBXawPositionSimpleMenu\fP action
  287. is realized.
  288. .NH 4
  289. Getting and Clearing the Current Menu Entry
  290. .LP
  291. To get the currently highlighted menu entry use
  292. \fBXawSimpleMenuGetActiveEntry\fP:
  293. .IN "XawSimpleMenuGetActiveEntry" "" "@DEF@"
  294. .FD 0
  295. Widget XawSimpleMenuGetActiveEntry(\fIw\fP)
  296. .br
  297.       Widget \fIw\fP;
  298. .FN
  299. .IP \fIw\fP 1i
  300. Specifies the SimpleMenu widget.
  301. .LP
  302. This function returns the menu entry that is
  303. currently highlighted, or NULL if no entry is highlighted. 
  304. .LP
  305. .sp
  306. To clear the SimpleMenu widget's internal information about the
  307. currently highlighted menu entry use
  308. \fBXawSimpleMenuClearActiveEntry\fP:
  309. .IN "XawSimpleMenuClearActiveEntry" "" "@DEF@"
  310. .FD 0
  311. Widget XawSimpleMenuClearActiveEntry(\fIw\fP)
  312. .br
  313.       Widget \fIw\fP;
  314. .FN
  315. .IP \fIw\fP 1i
  316. Specifies the SimpleMenu widget.
  317. .LP
  318. This function unsets all internal references to the currently
  319. highlighted menu entry.  It does not \fIunhighlight\fP or otherwise
  320. alter the appearance of the active entry.  This function is primarily
  321. for use by implementors of menu entries.
  322.