KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWMenu.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: vtkKWMenu.h,v
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWMenu - a menu widget
15 // .SECTION Description
16 // This class is the Menu abstraction.
17 
18 #ifndef __vtkKWMenu_h
19 #define __vtkKWMenu_h
20 
21 #include "vtkKWCoreWidget.h"
22 
23 class vtkKWMenuInternals;
24 
26 {
27 public:
28  static vtkKWMenu* New();
29  vtkTypeRevisionMacro(vtkKWMenu,vtkKWCoreWidget);
30  void PrintSelf(ostream& os, vtkIndent indent);
31 
32  // Description:
33  // Append/Insert a standard command menu item to the menu.
34  // The 'object' argument is the object that will have the method called on
35  // it. The 'method' argument is the name of the method to be called and any
36  // arguments in string form. If the object is NULL, the method is still
37  // evaluated as a simple command.
38  // A vtkKWMenu::CommandItemAddedEvent event is generated as well.
39  // Return index of the menu item that was created/inserted, -1 on error
40  virtual int AddCommand(const char *label);
41  virtual int AddCommand(const char *label,
42  vtkObject *object, const char *method);
43  virtual int InsertCommand(int index, const char *label);
44  virtual int InsertCommand(int index, const char *label,
45  vtkObject *object, const char *method);
46 
47  // Description:
48  // Set/Get the command for an existing menu item. This can also be used
49  // on checkbutton and radiobutton entries (i.e. any menu item that was
50  // created with a command).
51  // Note that the output of GetItemCommand is a pointer to a
52  // temporary buffer that should be copied *immediately* to your own storage.
53  virtual void SetItemCommand(
54  int index, vtkObject *object, const char *method);
55  virtual const char* GetItemCommand(int index);
56 
57  // Description:
58  // Get the index of the first menu item that is using a specific command.
59  // You can also use GetIndexOfItem to retrieve the menu item using a
60  // specific label.
61  virtual int GetIndexOfCommandItem(vtkObject *object, const char *method);
62 
63  // Description:
64  // Append/Insert a checkbutton menu item to the menu.
65  // A vtkKWMenu::CheckButtonItemAddedEvent event is generated as well.
66  // Return index of the menu item that was created/inserted, -1 on error
67  virtual int AddCheckButton(const char *label);
68  virtual int AddCheckButton(const char *label,
69  vtkObject *object, const char *method);
70  virtual int InsertCheckButton(int index, const char *label);
71  virtual int InsertCheckButton(int index, const char *label,
72  vtkObject *object, const char *method);
73 
74  // Description:
75  // Set/Get an checkbutton or radiobutton selected state (where 1
76  // means selected, 0 means deselected).
77  // Note that you can *not* set the selected state of a radiobutton to 0;
78  // a radiobutton is part of a group, to deselect it one needs to select
79  // another radiobutton in that group (therefore, unselecting a
80  // radiobutton has no meaning).
81  // Items can be referred to by index or label.
82  virtual void SetItemSelectedState(int index, int state);
83  virtual void SetItemSelectedState(const char *label, int state);
84  virtual int GetItemSelectedState(int index);
85  virtual int GetItemSelectedState(const char *label);
86 
87  // Description:
88  // Select/Deselect a checkbutton or radiobutton.
89  // These methods are just front-end to SetItemSelectedState. The same
90  // constraints apply, i.e. you can *not* deselect a radiobutton (but
91  // should select another radiobutton in the same group).
92  // Items can be referred to by index or label.
93  virtual void SelectItem(int index);
94  virtual void SelectItem(const char *label);
95  virtual void DeselectItem(int index);
96  virtual void DeselectItem(const char *label);
97 
98  // Description:
99  // Append/Insert a radiobutton menu item to the menu.
100  // Radiobuttons can be grouped together using either the
101  // PutItemInGroup method or the SetItemGroupName method.
102  // By default, each newly created radiobutton share the same group already.
103  // A vtkKWMenu::RadioButtonItemAddedEvent event is generated as well.
104  // Return index of the menu item that was created/inserted, -1 on error
105  virtual int AddRadioButton(const char *label);
106  virtual int AddRadioButton(const char *label,
107  vtkObject *object, const char *method);
108  virtual int InsertRadioButton(int index, const char *label);
109  virtual int InsertRadioButton(int index, const char *label,
110  vtkObject *object, const char *method);
111 
112  // Description:
113  // Append/Insert a radiobutton menu item to the menu using an image
114  // instead of a label. The image name should be a valid Tk image name.
115  // Radiobuttons can be grouped together using either the
116  // PutItemInGroup method or the SetItemGroupName method.
117  // By default, each newly created radiobutton share the same group already.
118  // A vtkKWMenu::RadioButtonItemAddedEvent event is generated as well.
119  // Return index of the menu item that was created/inserted, -1 on error
120  virtual int AddRadioButtonImage(const char *imgname);
121  virtual int AddRadioButtonImage(const char *imgname,
122  vtkObject *object, const char *method);
123  virtual int InsertRadioButtonImage(int index, const char *imgname);
124  virtual int InsertRadioButtonImage(int index, const char *imgname,
125  vtkObject *object, const char *method);
126 
127  // Description:
128  // Group items together so that when one is selected, the other
129  // ones are automatically deselected. This makes sense for radiobutton
130  // items where each item should be assigned a different 'selected value'
131  // using the SetItemSelectedValue method.
132  // This method puts the item specified by 'index' in the
133  // group the item specificied by 'index_g' is already a member of.
134  // Note that put(index_a, index_g) and put(index_b, index_g)
135  // will put index_a and index_b in the same group as index_g, but
136  // put(index_a, index_g) and put(index_g, index_b) will put
137  // index_a in the same group as index_g, then put index_g in the same
138  // group as index_b, thus resulting as index_a being in a different group
139  // as index_g/index_b.
140  // Another way to group items together is to make sure they all share the
141  // same group name (see SetItemGroupName), which is what is really done by
142  // PutItemInGroup anyway.
143  // By default, each newly created radiobutton share the same group already,
144  // new checkbuttons are assigned to their own group, and other items type
145  // have no group.
146  virtual void PutItemInGroup(int index, int index_g);
147 
148  // Description:
149  // Set/Get the *local* group name to use to group a set of items together
150  // (i.e. selecting one item in the group will deselect the others).
151  // This makes sense for radiobutton items where each item should
152  // be assigned a different 'selected value' using the SetItemSelectedValue
153  // method. Another way to group items together is to use the PutItemInGroup
154  // method, which at the end of the day will make sure items share the same
155  // group name.
156  // Note that the group name should be unique within *this* menu instance (if
157  // you need a global name that can be shared between menus, check the more
158  // advanced SetItemVariableName method). The group name should stick to
159  // the usual variable naming convention (no spaces, start with a letter,
160  // etc); note that it will be cleaned automatically anyway and
161  // stored that way.
162  // By default, each newly created radiobutton share the same group already,
163  // new checkbuttons are assigned to their own group, and other items type
164  // have no group.
165  virtual const char* GetItemGroupName(int index);
166  virtual void SetItemGroupName(int index, const char *group_name);
167 
168  // Description:
169  // Set/Get the value associated to the selected state of a checkbutton
170  // or radiobutton menu item. Convenience methods are provided to Set/Get
171  // that value as an integer.
172  // By default, checkbutton are assigned a selected value of 1. Radiobuttons
173  // are assigned a value corresponding to their own label (or image name).
174  // Note that the output of GetItemSelectedValue is a pointer to a
175  // temporary buffer that should be copied *immediately* to your own storage.
176  // Returns the value, or -1 if called on the wrong type of menu item
177  virtual void SetItemSelectedValue(int index, const char *value);
178  virtual const char* GetItemSelectedValue(int index);
179  virtual void SetItemSelectedValueAsInt(int index, int value);
180  virtual int GetItemSelectedValueAsInt(int index);
181 
182  // Description:
183  // Set/Get the index of an item given its selected value (as set by
184  // SetItemSelectedValue).
185  virtual int GetIndexOfItemWithSelectedValue(const char *value);
186  virtual int GetIndexOfItemWithSelectedValueAsInt(int value);
187 
188  // Description:
189  // Select the item which selected value (as it was set per item
190  // using SetItemSelectedValue) matches a given value. Convenience method is
191  // provided to select the item using a value as an integer.
192  // Returns the item that was selected, -1 otherwise.
193  virtual int SelectItemWithSelectedValue(const char *value);
194  virtual int SelectItemWithSelectedValueAsInt(int value);
195 
196  // Description:
197  // Select the item in a group which selected value (as it was set per item
198  // using SetItemSelectedValue) matches a given value. Convenience method is
199  // provided to select the item using a value as an integer.
200  // Returns the item that was selected, -1 otherwise.
201  virtual int SelectItemInGroupWithSelectedValue(
202  const char *group_name, const char *value);
203  virtual int SelectItemInGroupWithSelectedValueAsInt(
204  const char *group_name, int value);
205 
206  // Description:
207  // Get the index of the selected item in a group.
208  // If group is not specified, use the group of the last entry; note that
209  // this will only work there is only one group in the menu.
210  // Return -1 on error.
211  virtual int GetIndexOfSelectedItemInGroup(const char *group_name);
212  virtual int GetIndexOfSelectedItem();
213 
214  // Description:
215  // Set/Get the value associated to the de-selected state of a checkbutton
216  // menu item (no allowed for radiobuttons). Can be safely left as is
217  // most of the time, unless you want to store very specific selected
218  // and deselected values for a checkbutton and retrieve them later on.
219  // By default, checkbutton are assigned a selected value of 0. Radiobuttons
220  // do not have a deselected value: a radiobutton is part of a group, to
221  // deselect it one needs to select another radiobutton in that group
222  // (therefore, unselecting a radiobutton has no meaning).
223  // Note that the output of GetItemDeselectedValue is a pointer to a
224  // temporary buffer that should be copied *immediately* to your own storage.
225  // Returns the value, or -1 if called on the wrong type of menu item
226  virtual void SetItemDeselectedValue(int index, const char *value);
227  virtual void SetItemDeselectedValueAsInt(int index, int value);
228  virtual int GetItemDeselectedValueAsInt(int index);
229  virtual const char* GetItemDeselectedValue(int index);
230 
231  // Description:
232  // Append/Insert a separator to the menu.
233  // A vtkKWMenu::SeparatorItemAddedEvent event is generated as well.
234  // Return index of the menu item that was created/inserted, -1 on error
235  virtual int AddSeparator();
236  virtual int InsertSeparator(int index);
237 
238  // Description:
239  // Append/Insert a sub-menu (cascade) to the menu.
240  // A vtkKWMenu::CascadeItemAddedEvent event is generated as well.
241  // Return index of the menu item that was created/inserted, -1 on error
242  virtual int AddCascade(const char *label, vtkKWMenu *menu);
243  virtual int InsertCascade(int index, const char *label, vtkKWMenu *menu);
244 
245  // Description:
246  // Get the index of the first sub-menu (cascade) item that is using a
247  // specific menu object.
248  virtual int GetIndexOfCascadeItem(vtkKWMenu *menu);
249 
250  // Description:
251  // Set the sub-menu for an existing sub-menu (cascade) item.
252  virtual void SetItemCascade(int index, vtkKWMenu*);
253  virtual void SetItemCascade(int index, const char *menu_name);
254  virtual vtkKWMenu* GetItemCascade(int index);
255 
256  // Description:
257  // Returns the integer index of the menu item using a specific label.
258  // You can also use GetIndexOfCommandItem to retrieve the menu item using a
259  // specific command (if that menu item supports a command).
260  virtual int GetIndexOfItem(const char *label);
261 
262  // Description:
263  // Checks if an item with a given label is in the menu.
264  virtual int HasItem(const char *label);
265 
266  // Description:
267  // Returns the type of a specific menu item.
268  //BTX
269  enum
270  {
271  UnknownItemType = 0,
276  CascadeItemType
277  };
278  //ETX
279  virtual int GetItemType(int index);
280 
281  // Description:
282  // Set/Get the label of a specific menu item at a given index.
283  // Note that the output of GetItemLabel is a pointer to a
284  // temporary buffer that should be copied *immediately* to your own storage.
285  virtual int SetItemLabel(int index, const char *label);
286  virtual const char* GetItemLabel(int index);
287 
288  // Description:
289  // Call the callback/command of a specific menu item specified by its
290  // index.
291  virtual void InvokeItem(int index);
292 
293  // Description:
294  // Delete the menu item specified by its given index.
295  // Be careful, there is a bug in Tk, that will break other items
296  // in the menu below the one being deleted, unless a new item is added.
297  virtual void DeleteItem(int index);
298  virtual void DeleteAllItems();
299 
300  // Description:
301  // Returns the number of items.
302  virtual int GetNumberOfItems();
303 
304  // Description:
305  // Set/Get state of the menu item with a given index or label.
306  // Valid constants can be found in vtkKWOptions::StateType.
307  virtual void SetItemState(int index, int state);
308  virtual void SetItemStateToDisabled(int index);
309  virtual void SetItemStateToNormal(int index);
310  virtual void SetItemState(const char *label, int state);
311  virtual void SetItemStateToDisabled(const char *label);
312  virtual void SetItemStateToNormal(const char *label);
313  virtual int GetItemState(int index);
314  virtual int GetItemState(const char *label);
315 
316  // Description:
317  // Set the state of all entries.
318  // Valid constants can be found in vtkKWOptions::StateType.
319  // This should not be used directly, this is done by
320  // SetEnabled()/UpdateEnableState().
321  // Overriden to pass to all menu entries.
322  virtual void SetState(int state);
323 
324  // Description:
325  // Set the image of a menu item. A valid Tk image name or the index of
326  // a predefined icon (as found in vtkKWIcon) should be passed.
327  // Check the SetItemCompoundMode method if you want to display both the
328  // image and the label at the same time.
329  virtual void SetItemImage(int index, const char *imgname);
330  virtual void SetItemImageToPredefinedIcon(int index, int icon_index);
331  virtual void SetItemImageToIcon(int index, vtkKWIcon *icon);
332 
333  // Description:
334  // Set the select image of a menu item.
335  // The select image is available only for checkbutton and radiobutton
336  // entries. This method can be used to specify the image to display in
337  // the menu item when it is selected (instead of the regular image).
338  virtual void SetItemSelectImage(int index, const char *imgname);
339  virtual void SetItemSelectImageToPredefinedIcon(int index, int icon_index);
340  virtual void SetItemSelectImageToIcon(int index, vtkKWIcon *icon);
341 
342  // Description:
343  // Specifies if the menu item should display text and bitmaps/images at the
344  // same time, and if so, where the bitmap/image should be placed relative
345  // to the text.
346  // Valid constants can be found in vtkKWOptions::CompoundModeType.
347  // The (default) value CompoundModeNone specifies that the bitmap or image
348  // should (if defined) be displayed instead of the text.
349  // Check the SetItemMarginVisibility method too.
350  virtual void SetItemCompoundMode(int index, int mode);
351  virtual int GetItemCompoundMode(int index);
352  virtual void SetItemCompoundModeToNone(int index);
353  virtual void SetItemCompoundModeToLeft(int index);
354  virtual void SetItemCompoundModeToCenter(int index);
355  virtual void SetItemCompoundModeToRight(int index);
356  virtual void SetItemCompoundModeToTop(int index);
357  virtual void SetItemCompoundModeToBottom(int index);
358 
359  // Description:
360  // Set the visibility of the standard margin of a menu item.
361  // Hiding the margin is useful when creating palette with images in them,
362  // i.e., color palettes, pattern palettes, etc.
363  virtual void SetItemMarginVisibility(int index, int flag);
364 
365  // Description:
366  // Set the visibility of the indicator of a menu item.
367  // Available only for checkbutton and radiobutton entries.
368  virtual void SetItemIndicatorVisibility(int index, int flag);
369 
370  // Description:
371  // Specifies a string to display at the right side of the menu entry.
372  // Normally describes an accelerator keystroke sequence that may be typed
373  // to invoke the same function as the menu entry. This is an arbitrary
374  // string, not a key binding per say, i.e. pressing the accelerator
375  // key does not automatically call the command associated to this
376  // menu item. To do so, the corresponding key binding must be set and
377  // associated to the item's command, if any. The SetBindingForItemAccelerator
378  // method can be used to that effect.
379  virtual void SetItemAccelerator(int index, const char *accelerator);
380 
381  // Description:
382  // This method retrieves the accelerator attached to a menu item, convert
383  // it to the proper keybinding (say, Ctrl+0 is converted into <Control-0>),
384  // and set that binding on a specific 'widget' so that whenever that widget
385  // has the focus and that key binding is pressed, the item's command will
386  // be invokved. A typical use for this method is to set a menu item's
387  // accelerator using SetItemAccelerator, then associate the corresponding
388  // binding to the toplevel this menu is attached to. For example:
389  // menu->SetItemAccelerator(1, "Ctrl+0");
390  // menu->SetBindingForItemAccelerator(1, menu->GetParentTopLevel());
391  // this last line is pretty much the same as this one below:
392  // menu->GetParentTopLevel()->SetBinding(
393  // "<Control-0>", menu->GetItemCommand(1));
394  // but the accelerator to key-binding conversion is done automatically.
395  // Note that if the accelerator has not been set (or if it has been reset
396  // to an empty string or NULL), this method will *not* remove the binding
397  // (since it has no knowledge of what the previous accelerator was), this
398  // is up to the developper to do so by calling RemoveBinding for example.
399  virtual void SetBindingForItemAccelerator(int index, vtkKWWidget*);
400  virtual void RemoveBindingForItemAccelerator(int index, vtkKWWidget*);
401 
402  // Description:
403  // Set/Get the help string for a given item specified by its index.
404  // The help string will be displayed automatically in the status bar
405  // of the window containing the menu, if any.
406  // Note that the output of GetItemHelpString is a pointer to a
407  // temporary buffer that should be copied *immediately* to your own storage.
408  virtual void SetItemHelpString(int index, const char *help);
409  virtual const char* GetItemHelpString(int index);
410 
411  // Description:
412  // Set the index of a character to underline in the menu item specified by
413  // its index. Note that you can also specify that character
414  // by using the special '&' marker in the label of the menu item
415  // (ex: "&File", or "Sa&ve File").
416  virtual void SetItemUnderline(int index, int underline_index);
417 
418  // Description:
419  // Set/Get a column break flag at a specific index.
420  virtual void SetItemColumnBreak(int index, int flag);
421 
422  // Description:
423  // Set/Get the name of a *global* variable to set when a checkbutton or a
424  // radiobutton menu item is selected. Whenever selected, a checkbutton
425  // or radiobutton will set its variable to the value that was associated
426  // to it using SetItemSelectedValue. When deselected a checkbutton set
427  // its variable to the value that was associated to it using
428  // SetItemDeselectedValue.
429  // Setting the same variable names for different radiobuttons is the
430  // actual way to put them in the same *group* (i.e. selecting one
431  // radiobutton in the group will deselect the others). Is is recommended
432  // to use either the PutItemInGroup method to group buttons
433  // together, or the SetItemGroupName method, which are just
434  // front-ends to the SetItemVariable method, but build a global variable
435  // name out of the current menu instance name and a local group name.
436  // Note that the variable name should be unique within *this* menu
437  // instance as well as *all* other menu instances so that it can be
438  // shared between menus if needed. Most of the time, using a global name
439  // will not be needed and we therefore recommend you pick a local global
440  // name by using the SetItemGroupName. This variable name should
441  // stick to the usual variable naming convention (no spaces, start with
442  // a letter, etc). One way to create such a group name is, for example, to
443  // concatenate the Tcl name (GetTclName()) or the widget name
444  // (GetWidgetName()) of the menu instance with some string suffix
445  // describing the variable; a different signature is available to create
446  // such composite name automatically, but the CreateItemVariableName can
447  // be used as well.
448  // By default, each newly created radiobutton share the same variable
449  // name already. Each newly created checkbutton is assigned a unique
450  // variable name.
451  // Note that the output of GetItemVariable is a pointer to a
452  // temporary buffer that should be copied *immediately* to your own storage.
453  virtual const char* GetItemVariable(int index);
454  virtual void SetItemVariable(int index, const char *varname);
455  virtual void SetItemVariable(
456  int index, vtkKWObject *object, const char *suffix);
457 
458  // Description:
459  // Convenience method to create a variable name out of an object
460  // (say, this instance) and an arbitrary suffix (say, the menu item label).
461  // Such a variable name can be used to call SetItemVariable on a
462  // checkbutton or radiobutton menu item.
463  // Note that spaces and unusual characters are automatically removed
464  // from the 'suffix'.
465  // This method allocates enough memory (using 'new') for that name and
466  // returns a pointer to that location. This pointer should be deleted
467  // by the user using 'delete []'.
468  virtual char* CreateItemVariableName(
469  vtkKWObject *object, const char *suffix);
470 
471  // Description:
472  // Set/Get the value for a variable name given a variable name (as retrieved
473  // using GetItemVariable() for example).
474  // This will affect the menu entries accordingly (i.e. setting the
475  // variable will select/deselect the entries).
476  // Note that the output of GetItemVariableValue is a pointer to a
477  // temporary buffer that should be copied *immediately* to your own storage.
478  virtual const char* GetItemVariableValue(const char *varname);
479  virtual void SetItemVariableValue(const char *varname, const char *value);
480  virtual int GetItemVariableValueAsInt(const char *varname);
481  virtual void SetItemVariableValueAsInt(const char *varname, int value);
482 
483  // Description:
484  // Get the index of an item gien its variable name and its selected value.
485  virtual int GetIndexOfItemWithVariableAndSelectedValue(
486  const char *varname, const char *value);
487  virtual int GetIndexOfItemWithVariableAndSelectedValueAsInt(
488  const char *varname, int value);
489 
490  // Description:
491  // Set/Get if this menu is a tearoff menu. By dafault this value is off.
492  virtual void SetTearOff(int val);
493  vtkGetMacro(TearOff, int);
494  vtkBooleanMacro(TearOff, int);
495 
496  // Description:
497  // Pop-up the menu at screen coordinates x, y
498  virtual void PopUp(int x, int y);
499 
500  // Description:
501  // Get the Tk option of a specific menu item. Internal use.
502  // Note that the output of GetItemOption is a pointer to a
503  // temporary buffer that should be copied *immediately* to your own storage.
504  virtual int HasItemOption(int index, const char *option);
505  virtual const char* GetItemOption(int index, const char *option);
506 
507  // Description:
508  // Events. The ItemAddedEvent events are generated when menu entries are
509  // addded or inserted (say, RadioButtonItemAddedEvent).
510  // The MenuItemInvokedEvent is sent when a menu entry is invoked (i.e.,
511  // a mouse button is released over the entry).
512  // The following parameters are also passed as client data:
513  // - the index of the new menu item: int
514  //BTX
515  enum
516  {
517  RadioButtonItemAddedEvent = 10000,
522  MenuItemInvokedEvent
523  };
524  //ETX
525 
526  // Description:
527  // Set/Get the background color of the widget.
528  virtual void GetBackgroundColor(double *r, double *g, double *b);
529  virtual double* GetBackgroundColor();
530  virtual void SetBackgroundColor(double r, double g, double b);
531  virtual void SetBackgroundColor(double rgb[3])
532  { this->SetBackgroundColor(rgb[0], rgb[1], rgb[2]); };
533 
534  // Description:
535  // Set/Get the foreground color of the widget.
536  virtual void GetForegroundColor(double *r, double *g, double *b);
537  virtual double* GetForegroundColor();
538  virtual void SetForegroundColor(double r, double g, double b);
539  virtual void SetForegroundColor(double rgb[3])
540  { this->SetForegroundColor(rgb[0], rgb[1], rgb[2]); };
541 
542  // Description:
543  // Set/Get the active background color of the widget. An element
544  // (a widget or portion of a widget) is active if the mouse cursor is
545  // positioned over the element and pressing a mouse button will cause some
546  // action to occur.
547  virtual void GetActiveBackgroundColor(double *r, double *g, double *b);
548  virtual double* GetActiveBackgroundColor();
549  virtual void SetActiveBackgroundColor(double r, double g, double b);
550  virtual void SetActiveBackgroundColor(double rgb[3])
551  { this->SetActiveBackgroundColor(rgb[0], rgb[1], rgb[2]); };
552 
553  // Description:
554  // Set/Get the active foreground color of the widget. An element
555  // (a widget or portion of a widget) is active if the mouse cursor is
556  // positioned over the element and pressing a mouse button will cause some
557  // action to occur.
558  virtual void GetActiveForegroundColor(double *r, double *g, double *b);
559  virtual double* GetActiveForegroundColor();
560  virtual void SetActiveForegroundColor(double r, double g, double b);
561  virtual void SetActiveForegroundColor(double rgb[3])
562  { this->SetActiveForegroundColor(rgb[0], rgb[1], rgb[2]); };
563 
564  // Description:
565  // Set/Get the foreground color of the widget when it is disabled.
566  virtual void GetDisabledForegroundColor(double *r, double *g, double *b);
567  virtual double* GetDisabledForegroundColor();
568  virtual void SetDisabledForegroundColor(double r, double g, double b);
569  virtual void SetDisabledForegroundColor(double rgb[3])
570  { this->SetDisabledForegroundColor(rgb[0], rgb[1], rgb[2]); };
571 
572  // Description:
573  // Set/Get the background color to use when the widget is selected.
574  virtual void GetSelectColor(double *r, double *g, double *b);
575  virtual double* GetSelectColor();
576  virtual void SetSelectColor(double r, double g, double b);
577  virtual void SetSelectColor(double rgb[3])
578  { this->SetSelectColor(rgb[0], rgb[1], rgb[2]); };
579 
580  // Description:
581  // Set/Get the border width, a non-negative value indicating the width of
582  // the 3-D border to draw around the outside of the widget (if such a border
583  // is being drawn; the Relief option typically determines this).
584  virtual void SetBorderWidth(int);
585  virtual int GetBorderWidth();
586 
587  // Description:
588  // Set/Get the 3-D effect desired for the widget.
589  // The value indicates how the interior of the widget should appear
590  // relative to its exterior.
591  // Valid constants can be found in vtkKWOptions::ReliefType.
592  virtual void SetRelief(int);
593  virtual int GetRelief();
594  virtual void SetReliefToRaised();
595  virtual void SetReliefToSunken();
596  virtual void SetReliefToFlat();
597  virtual void SetReliefToRidge();
598  virtual void SetReliefToSolid();
599  virtual void SetReliefToGroove();
600 
601  // Description:
602  // Specifies the font to use when drawing text inside the widget.
603  // You can use predefined font names (e.g. 'system'), or you can specify
604  // a set of font attributes with a platform-independent name, for example,
605  // 'times 12 bold'. In this example, the font is specified with a three
606  // element list: the first element is the font family, the second is the
607  // size, the third is a list of style parameters (normal, bold, roman,
608  // italic, underline, overstrike). Example: 'times 12 {bold italic}'.
609  // The Times, Courier and Helvetica font families are guaranteed to exist
610  // and will be matched to the corresponding (closest) font on your system.
611  // If you are familiar with the X font names specification, you can also
612  // describe the font that way (say, '*times-medium-r-*-*-12*').
613  virtual void SetFont(const char *font);
614  virtual const char* GetFont();
615 
616  // Description:
617  // Set or get enabled state.
618  // This method has been overriden to propagate the state to all its
619  // menu entries by calling UpdateEnableState(), *even* if the
620  // state (this->Enabled) is actually unchanged by the function. This
621  // make sure all the menu entries have been enabled/disabled properly.
622  virtual void SetEnabled(int);
623 
624  // Description:
625  // This method has been overriden to propagate the state to all its
626  // menu entries by calling SetState().
627  // Update the "enable" state of the object and its internal parts.
628  // Depending on different Ivars (this->Enabled, the application's
629  // Limited Edition Mode, etc.), the "enable" state of the object is updated
630  // and propagated to its internal parts/subwidgets. This will, for example,
631  // enable/disable parts of the widget UI, enable/disable the visibility
632  // of 3D widgets, etc.
633  virtual void UpdateEnableState();
634 
635  // Description:
636  // Callbacks: for active menu item doc line help
637  virtual void DisplayHelpCallback(const char *widget_name);
638  virtual void CommandInvokedCallback(const char *command);
639 
640 protected:
641  vtkKWMenu();
642  ~vtkKWMenu();
643 
644  // Description:
645  // Create the widget.
646  virtual void CreateWidget();
647 
648  // Description:
649  // Add a generic menu item (defined by type)
650  // Return index of the menu item that was created/inserted, -1 on error
651  virtual int AddGeneric(const char *type, const char *label,
652  const char* extra);
653  virtual int InsertGeneric(int index, const char *type, const char *label,
654  const char* extra);
655 
656  // Description:
657  // Given a label, allocate and create a clean label that is stripped
658  // out of its underline marker (ex: "&Open File" is cleaned as "Open File",
659  // "Sa&ve File" is cleaned as "Save File").
660  // Return 1 if a clean label was created: the 'clean_label' parameter
661  // should be freed later on by the user by calling 'delete []'. The
662  // 'underline' parameter is set to the position of the underline marker.
663  // Return 0 if the label was already cleaned: the 'clean_label' parameter
664  // is set to the value of 'label' (set, *not* allocated). The
665  // 'underline' parameter is set to -1.
666  virtual int GetLabelWithoutUnderline(
667  const char *label, char **clean_label, int *underline_index);
668 
669  int TearOff;
670 
671  // Description:
672  // Returns the integer index of the active menu item of a given menu.
673  // Be extra careful with this method: most menus seems to be clone of
674  // themselves, according to the Tk doc:
675  // When a menu is set as a menubar for a toplevel window, or when a menu
676  // is torn off, a clone of the menu is made. This clone is a menu widget
677  // in its own right, but it is a child of the original. Changes in the
678  // configuration of the original are reflected in the clone. Additionally,
679  // any cascades that are pointed to are also cloned so that menu traversal
680  // will work right.
681  // Sadly, the active item of a menu is not something that is synchronized
682  // between a menu and its clone. Querying the active item on the current
683  // instance might therefore not work, because a clone is in fact being
684  // interacted upon. This kind of situation is mostly encountered when
685  // Tk events like <<MenuSelect>> are processed, and can therefore be solved
686  // by making sure the callbacks are passing the %W parameter around: this
687  // gets resolved to the widget name of the clone.
688  virtual int GetIndexOfActiveItem(const char *widget_name);
689 
690  // Description:
691  // Get the suffix out of variable name that was created using
692  // CreateItemVariableName
693  const char* GetSuffixOutOfCreatedItemVariableName(const char *varname);
694 
695  // Description:
696  // Convert key accelerator to binding
697  virtual void ConvertItemAcceleratorToKeyBinding(
698  const char *accelerator, char **keybinding);
699 
700  // Description:
701  // PIMPL Encapsulation for STL containers
702  vtkKWMenuInternals *Internals;
703 
704 private:
705 
706  vtkKWMenu(const vtkKWMenu&); // Not implemented
707  void operator=(const vtkKWMenu&); // Not implemented
708 };
709 
710 #endif