KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWScaleWithEntry.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWScaleWithEntry.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 vtkKWScaleWithEntry - a scale widget with a label and entry
15 // .SECTION Description
16 // A widget that represents a more complex scale (or slider) with options for
17 // positioning a label, displaying an entry, working in popup mode, etc.
18 // For a more lightweight widget, check vtkKWScale.
19 // The label position and visibility can be changed through the
20 // vtkKWWidgetWithLabel superclass methods (see SetLabelPosition).
21 // The default position for the label is on the left of the scale for
22 // horizontal scales, on the right (top corner) for vertical ones.
23 // The default position for the entry is on the right of the scale for
24 // horizontal scales, on the right (bottom corner) for vertical ones.
25 // Both label and entry are visible by default.
26 // For convenience purposes, an empty label is not displayed though (make
27 // sure you use the SetLabelText method to set the label).
28 // In popup mode, a small button replaces the scale. Pressing that button
29 // will popup a scale the user can interact with, until it leaves the scale
30 // focus, which will withdraw the popup automatically. In that mode, the
31 // label and entry position are always displayed side by side, horizontally.
32 // Many of the vtkKWScale methods have been added to this API for
33 // convenience purposes, but GetScale() can be used to retrieve the
34 // internal vtkKWScale and access the rest of the API.
35 // .SECTION See Also
36 // vtkKWScale vtkKWScaleWithLabel vtkKWWidgetWithLabel
37 
38 #ifndef __vtkKWScaleWithEntry_h
39 #define __vtkKWScaleWithEntry_h
40 
41 #include "vtkKWScaleWithLabel.h"
42 
43 class vtkKWEntry;
44 class vtkKWLabel;
45 class vtkKWPushButton;
46 class vtkKWTopLevel;
47 
49 {
50 public:
51  static vtkKWScaleWithEntry* New();
53  void PrintSelf(ostream& os, vtkIndent indent);
54 
55  // Description:
56  // Set the range for this scale.
57  virtual void SetRange(double min, double max);
58  virtual void SetRange(const double *range)
59  { this->SetRange(range[0], range[1]); };
60  virtual double *GetRange();
61  virtual void GetRange(double &min, double &max);
62  virtual void GetRange(double range[2])
63  { this->GetRange(range[0], range[1]); };
64  virtual double GetRangeMin() { return this->GetRange()[0]; };
65  virtual double GetRangeMax() { return this->GetRange()[1]; };
66 
67  // Description:
68  // Set/Get the value of the scale.
69  virtual void SetValue(double v);
70  virtual double GetValue();
71 
72  // Description:
73  // Set/Get the resolution of the slider.
74  virtual void SetResolution(double r);
75  virtual double GetResolution();
76 
77  // Description:
78  // Turn on/off the automatic clamping of the end values when the
79  // user types a value beyond the range. Default is on.
80  virtual void SetClampValue(int);
81  virtual int GetClampValue();
82  vtkBooleanMacro(ClampValue, int);
83 
84  // Description:
85  // Get the internal vtkKWScale.
86  // Retrive that object to set the resolution, range, value, etc.
87  virtual vtkKWScale* GetScale()
88  { return this->GetWidget(); };
89 
90  // Description:
91  // Set/Get whether to display the range of the scale.
92  // If the scale orientation is horizontal, the min is displayed on the
93  // left of the scale, the max range on the right. For vertical orientation,
94  // min is on top, max at the bottom. In popup mode, the range is
95  // displayed directly in the popup window using the same layout as above.
96  void SetRangeVisibility(int flag);
97  vtkGetMacro(RangeVisibility, int);
98  vtkBooleanMacro(RangeVisibility, int);
99 
100  // Description:
101  // Set/Get the internal entry visibility (On by default).
102  // IMPORTANT: if you know you may not show the entry, try to
103  // set that flag as early as possible (ideally, before calling Create())
104  // in order to lower the footprint of the widget: the entry will not be
105  // allocated and created if there is no need to show it.
106  // Later on, you can still use that option to show the entry: it will be
107  // allocated and created on the fly.
108  virtual void SetEntryVisibility(int);
109  vtkBooleanMacro(EntryVisibility, int);
110  vtkGetMacro(EntryVisibility, int);
111 
112  // Description:
113  // Set the contents label.
114  // IMPORTANT: this method will create the label on the fly, use it only if
115  // you are confident that you will indeed display the label.
116  // Override the superclass so that the label is packed/unpacked if the
117  // text value is an empty string.
118  virtual void SetLabelText(const char *);
119 
120  // Description:
121  // Get the internal entry.
122  // IMPORTANT: the internal entry is "lazy created", i.e. it is neither
123  // allocated nor created until GetEntry() is called. This allows
124  // for a lower footprint and faster UI startup. Therefore, do *not* use
125  // GetEntry() to check if the entry exists, as it will automatically
126  // allocate the entry. Use HasEntry() instead.
127  virtual vtkKWEntry* GetEntry();
128  virtual int HasEntry();
129 
130  // Description:
131  // Set/Get the entry width.
132  // IMPORTANT: this method will create the entry on the fly, use it only if
133  // you are confident that you will indeed display the entry.
134  virtual void SetEntryWidth(int width);
135  virtual int GetEntryWidth();
136 
137  // Description:
138  // If supported, set the entry position in regards to the rest of
139  // the composite widget. Check the subclass for more information about
140  // what the Default position is, and if specific positions are supported.
141  // The default position for the entry is on the right of the scale for
142  // horizontal scales, on the right (bottom corner) for vertical ones.
143  // Remember that the label position and visibility can also be changed
144  // through the vtkKWWidgetWithLabel superclass methods (SetLabelPosition).
145  //BTX
146  enum
147  {
148  EntryPositionDefault = 0,
152  EntryPositionRight
153  };
154  //ETX
155  virtual void SetEntryPosition(int);
156  vtkGetMacro(EntryPosition, int);
157  virtual void SetEntryPositionToDefault()
158  { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionDefault); };
159  virtual void SetEntryPositionToTop()
160  { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionTop); };
161  virtual void SetEntryPositionToBottom()
162  { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionBottom); };
163  virtual void SetEntryPositionToLeft()
164  { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionLeft); };
165  virtual void SetEntryPositionToRight()
166  { this->SetEntryPosition(vtkKWScaleWithEntry::EntryPositionRight); };
167 
168  // Description:
169  // Set both the label and entry position to the top of the scale
170  // (label in the left corner, entry in the right corner)
171  virtual void SetLabelAndEntryPositionToTop();
172 
173  // Description:
174  // Set/Get a popup scale.
175  // WARNING: must be set *before* Create() is called.
176  vtkSetMacro(PopupMode, int);
177  vtkGetMacro(PopupMode, int);
178  vtkBooleanMacro(PopupMode, int);
179  vtkGetObjectMacro(PopupPushButton, vtkKWPushButton);
180 
181  // Description:
182  // Set/Get the entry expansion flag. This flag is only used if PopupMode
183  // mode is On. In that case, the default behaviour is to provide a widget
184  // as compact as possible, i.e. the Entry won't be expanded if the widget
185  // grows. Set ExpandEntry to On to override this behaviour.
186  virtual void SetExpandEntry(int flag);
187  vtkGetMacro(ExpandEntry, int);
188  vtkBooleanMacro(ExpandEntry, int);
189 
190  // Description:
191  // Set/Get the orientation type.
192  // For widgets that can lay themselves out with either a horizontal or
193  // vertical orientation, such as scales, this option specifies which
194  // orientation should be used.
195  // Valid constants can be found in vtkKWOptions::OrientationType.
196  virtual void SetOrientation(int);
197  virtual int GetOrientation();
198  virtual void SetOrientationToHorizontal();
199  virtual void SetOrientationToVertical();
200 
201  // Description
202  // Set/Get the desired long dimension of the scale.
203  // For vertical scales this is the scale's height, for horizontal scales
204  // it is the scale's width. In pixel.
205  virtual void SetLength(int length);
206  virtual int GetLength();
207 
208  // Description:
209  // Specifies commands to associate with the widget.
210  // 'Command' is invoked when the widget value is changing (i.e. during
211  // user interaction).
212  // 'StartCommand' is invoked at the beginning of a user interaction with
213  // the widget (when a mouse button is pressed over the widget for example).
214  // 'EndCommand' is invoked at the end of the user interaction with the
215  // widget (when the mouse button is released for example).
216  // 'EntryCommand' is invoked when the widget value is changed using
217  // the text entry.
218  // The need for a 'Command', 'StartCommand' and 'EndCommand' can be
219  // explained as follows: 'EndCommand' can be used to be notified about any
220  // changes made to this widget *after* the corresponding user interaction has
221  // been performed (say, after releasing the mouse button that was dragging
222  // a slider, or after clicking on a checkbutton). 'Command' can be set
223  // *additionally* to be notified about the intermediate changes that
224  // occur *during* the corresponding user interaction (say, *while* dragging
225  // a slider). While setting 'EndCommand' is enough to be notified about
226  // any changes, setting 'Command' is an application-specific choice that
227  // is likely to depend on how fast you want (or can) answer to rapid changes
228  // occuring during a user interaction, if any. 'StartCommand' is rarely
229  // used but provides an opportunity for the application to modify its
230  // state and prepare itself for user-interaction; in that case, the
231  // 'EndCommand' is usually set in a symmetric fashion to set the application
232  // back to its previous state.
233  // The 'object' argument is the object that will have the method called on
234  // it. The 'method' argument is the name of the method to be called and any
235  // arguments in string form. If the object is NULL, the method is still
236  // evaluated as a simple command.
237  // Note that the same events as vtkKWScale are generated, as a convenience.
238  // The following parameters are also passed to the command:
239  // - the current value: double
240  virtual void SetCommand(vtkObject *object, const char *method);
241  virtual void SetStartCommand(vtkObject *object, const char *method);
242  virtual void SetEndCommand(vtkObject *object, const char *method);
243  virtual void SetEntryCommand(vtkObject *object, const char *method);
244 
245  // Description:
246  // Events. IMPORTANT: this widget is a composite widget that assembles
247  // both a vtkKWScale (which can be retrieved using GetScale()) and a
248  // (which can be retrieved using GetEntry()). Events are generated by
249  // both classes separately (see the corresponding class documentation).
250  // HOWEVER, for convenience purposes, an instance of vtkKWScaleWithEntry
251  // will emit (i.e. forward) the events that were sent by its internal
252  // vtkKWScale automatically, just as if they were sent by the instance
253  // itself. Therefore, you do not need to listen to the internal GetScale()
254  // or GetEntry() objects, but to the instance directly.
255  // Check the vtkKWScale documentation for the list of events.
256  // (for example, vtkKWScale::ScaleValueChangingEvent,
257  // vtkKWScale::ScaleValueChangedEvent,
258  // vtkKWScale::ScaleValueStartChangingEvent, etc).
259 
260  // Description:
261  // Set/Get whether the above commands should be called or not.
262  // This make it easier to disable the commands while setting the scale
263  // value for example.
264  virtual void SetDisableCommands(int);
265  virtual int GetDisableCommands();
266  vtkBooleanMacro(DisableCommands, int);
267 
268  // Description:
269  // Setting this string enables balloon help for this widget.
270  // Override to pass down to children for cleaner behavior
271  virtual void SetBalloonHelpString(const char *str);
272 
273  // Description:
274  // Update the "enable" state of the object and its internal parts.
275  // Depending on different Ivars (this->Enabled, the application's
276  // Limited Edition Mode, etc.), the "enable" state of the object is updated
277  // and propagated to its internal parts/subwidgets. This will, for example,
278  // enable/disable parts of the widget UI, enable/disable the visibility
279  // of 3D widgets, etc.
280  virtual void UpdateEnableState();
281 
282  // Description:
283  // Callbacks. Internal, do not use.
284  virtual void DisplayPopupModeCallback();
285  virtual void WithdrawPopupModeCallback();
286  virtual void EntryValueCallback(const char *value);
287  virtual void ScaleValueCallback(double num);
288 
289  // Description:
290  // Add all the default observers needed by that object, or remove
291  // all the observers that were added through AddCallbackCommandObserver.
292  // Subclasses can override these methods to add/remove their own default
293  // observers, but should call the superclass too.
294  virtual void AddCallbackCommandObservers();
295  virtual void RemoveCallbackCommandObservers();
296 
297 protected:
300 
301  // Description:
302  // Create the widget.
303  virtual void CreateWidget();
304 
305  // Description:
306  // Bind/Unbind all components so that values can be changed, but
307  // no command will be called.
308  void Bind();
309  void UnBind();
310 
313 
314  virtual void InvokeEntryCommand(double value);
316 
320 
323 
326 
327  // Description:
328  // Pack or repack the widget. To be implemented by subclasses.
329  virtual void Pack();
330 
331  // Description:
332  // Create the entry
333  virtual void CreateEntry();
334 
335  // Description:
336  // Update internal widgets value
337  virtual void UpdateValue();
338  virtual void SetEntryValue(double num);
339  virtual void UpdateRange();
340 
341  // Description:
342  // Processes the events that are passed through CallbackCommand (or others).
343  // Subclasses can oberride this method to process their own events, but
344  // should call the superclass too.
345  virtual void ProcessCallbackCommandEvents(
346  vtkObject *caller, unsigned long event, void *calldata);
347 
348 private:
349 
350  // Description:
351  // Internal entry
352  // In 'private:' to allow lazy evaluation. GetEntry() will create the
353  // entry if it does not exist. This allow the object to remain lightweight.
354  vtkKWEntry *Entry;
355 
356  vtkKWScaleWithEntry(const vtkKWScaleWithEntry&); // Not implemented
357  void operator=(const vtkKWScaleWithEntry&); // Not implemented
358 };
359 
360 
361 #endif
362 
363 
364