This widget only has default functionality and is generally not instantiated,
but used as a base class for all WDS widget classes.
virtual WDS_Typecode GetTypeCode(void)
virtual char *GetTypeName(void)
Set/Return the type code or text class name of the widget,
a value unique to each derived class.
WDS_Typecode is currently a long refering to the address
of a static value of each specific type-coded class.
This can be used to identify widgets as being of a certain derived class.
This is a virtual function, and by default, returns WDS_TYPE_DEFAULT.
To be distiguishable,
a derived widget must insert the following in their class definition:
WDS_DECLARE_TYPE( class_name );This macro ends with the default "private:" permission setting, and, for consistancy, should appear first in the class declaration. Also, the macro
WDS_DEFINE_TYPE( class_name );should appear in a ".cc" source file, preferably the file directly associated with the class header. As a virtual, GetTypeCode() can be used on a generic casted-to WDS_Widget and still get the correct type code for the pointed-to widget.
This method requires an instantiated object for comparison.
For example, to determine if an unspecified widget
is a WDS_Button, you might do:
WDS_Widget *widget=something; WDS_Button button; if( widget->GetTypeCode() == button->GetTypeCode() ) ;// is a WDS_ButtonBut, every widget using the WDS_DECLARE_TYPE macro has an additional static member function static WDS_Typecode GetTypeCodeStatic(void) which can be accessed without instantiation like:
WDS_Widget *widget=something; if( widget->GetTypeCode() == WDS_Button::GetTypeCodeStatic() ) ; // is a WDS_ButtonNote that this value can vary between compilations and executions, so it's actual value should not be used for anything requiring consistancy between executions.
WDS_Widget *FindWidgetType(WDS_Typecode code,long first)
Return an ancestral widget matching the specified
WDS_Typecode code.
If first is TRUE,
the first match found while ascending the hierarchy is returned.
Otherwise, the search continues to the root,
finding the match nearest to the root.
This function is commonly used to find an ancestral scope.
void BevelBox(long force_clear,long annotate,WDS_String *bevelstring,long subx,long suby,long subsx,long subsy)
void BevelBox(long force_clear,long annotate,WDS_String *bevelstring)
void BevelBox(long force_clear,WDS_String *bevelstring)
Draw the widget using the wdsBevelBox() function with the general specifications of the widget.
The force_clear option will can be used to force a central fill.
The bevelstring is passed to wdsBevelBox()
to be written as text within the widget.
If specified, a subregion of origin subx, suby
and size subsx, subsy
is used instead of the default region of the full widget.
Widgets are not required to use the bevel box for their redrawing,
but it provides consistancy and convenience for normal widgets.
The annotation is used only if annotate is non-zero.
In the version of BevelBox() where annotate is not specified,
TRUE is used.
void ModifyPointDirection(long state,long vertical,long back)
This changes the arrow-point direct of the widget's border look specification.
The new direction vertical if and only if vertical is TRUE,
and toward the left or bottom if and only if back is TRUE.
The state to which the change is made is specified as per
WDS_Look::SetElement().
This calls has no effect on border settings that are not arrow-points.
WDS_Help *GetHelp(void)
Return the help object used by the widget.
long SpawnHelp(void)
Spawn a help reader for the widget.
This will only have effect if appropriate help software is installed.
virtual void ChangeState(long newstate,EW_Event *event)
void ChangeStateIfDifferent(long newstate,EW_Event *event)
General purpose state change.
Default ChangeState() sets the state to the newstate
and calls the state-change callback of the specified
newstate if specified by SetStateChangeCallback().
This virtual can be replaced.
ChangeStateIfDifferent() calls ChangeState() only if
newstate is different than the current state.
long GetGeneralFlags(void)
void SetGeneralFlags(long set)
void SetGeneralFlagsIncluding(long set)
void SetGeneralFlagsExcluding(long set)
Set general widget flags as the OR'ed sum of the following.
Enumeration values are given for clarity; they are subject to change.
| WDS_WIDGET_FLAGS_NONE 0 |
No general flags.
|
| WDS_WIDGET_FLAGS_AUTOPREF_X 1 |
Automatically set the pref size in the horizontal direction based on contents,
usually the label.
|
| WDS_WIDGET_FLAGS_AUTOSIZE_X 3 |
Automatically set the pref, min, and max size in the horizontal direction based on contents,
usually the label.
|
| WDS_WIDGET_FLAGS_AUTOPREF_Y 4 |
Automatically set the pref size in the vertical direction based on contents,
usually the label.
|
| WDS_WIDGET_FLAGS_AUTOSIZE_Y 12 |
Automatically set the pref, min, and max size in the vertical direction based on contents,
usually the label.
|
| WDS_WIDGET_FLAGS_AUTOPREF (WDS_WIDGET_FLAGS_AUTOPREF_X| WDS_WIDGET_FLAGS_AUTOPREF_Y) |
Automatically set the pref size in both directions.
|
| WDS_WIDGET_FLAGS_AUTOSIZE (WDS_WIDGET_FLAGS_AUTOSIZE_X| WDS_WIDGET_FLAGS_AUTOSIZE_Y) |
Automatically set the pref, min, and max size in both directions.
|
| WDS_WIDGET_FLAGS_DEFAULT (WDS_WIDGET_FLAGS_NONE) |
By default, no flags are set.
|
void SetWidgetState(long set)
long GetWidgetState(void)
Set/Get the state of the widget, often boolean, but not neccessarily.
Unlike ChangeState(), SetWidgetState() does not trigger any callbacks.
void SetStateChangeCallback(long for_state,void (*fp)(WDS_Activation *),WDS_Activation *act)
Sets the callback fp to be called during a state change during the default
ChangeState().
The WDS_Activation act
can be used in whatever way the widget or application wishes
in order to differentiate what occured.
This can be very useful if the same callback is used for different
widgets and/or effects. Note that the activation act is copied upon
calling SetStateChangeCallback.
WDS_Look *GetLocalLook(void)
Return the specific look for this particular object instance.
void SetLooks(WDS_Looks *set)
WDS_Look *GetLooks(void)
Set/Get the list of looks for the current configuration.
WDS_Look *GetDefaultLooks(void)
Get the list of default looks for when the set looks are NULL.
long InterpretElement(long state,long element)
For the given state,
get the appropriate value for given element
by interpreting the widget instance's look and the look lists.
void SetAnnotatable(long set) (protected)
long GetAnnotatable(void)
Set/Get the ability to be annotated.
The protected member function SetAnnotatable()
is generally set in the widget's constructor if it is capable
of being annotated.
GetAnnotatable() is generally be called from widget instances
to see if annotating is available for that widget.
By default, the annotating capability is FALSE.
void SetAnnotation(char *set)
WDS_String *GetAnnotation(void)
Set/Get the annotation text. The annotation text can contain
newline characters for multi-line annotations.
void SetLocalAnnotationSize(long x,long y) (convenience function)
Set the annotation size by altering the instance's look specification.
This space is taken from the total geometry of the widget.
If the given annotation size is too small,
more space will be used to fit the annotation text.
As such, an annotation size of (-1,-1) effectively
causes annotation auto-sizing.
void GetAnnotationGeometry(long *x,long *y,long *sx,long *sy)
Set the true geometry in window coordinates of the region within which
the annotation will be drawn.
void SetTipMode(long set)
long GetTipMode(void)
Set/Get the tipping flags as follows.
Enumeration values are given for clarity; they are subject to change.
| WDS_TIP_OFF 0 |
No tipping.
|
| WDS_TIP_ON 1 |
Use tipping.
|
void SetTipText(char *text)
char *GetTipText(void)
WDS_String *GetTipString(void)
Set/Get the text in tip (which can contain newline characters).
The text can be obtained as a character array or as the actual WDS_String.
static void DenyTips(void)
static void AllowTips(void)
static long GetDenyTips(void)
Increment/Decrement/Get a semaphore-like counter that prevents tipping when non-zero.
Widgets that enter a state that conflicts with tipping increment the count (deny).
All denials much have a matching AllowTips(), like pushing and poping a stack.
Note that although DenyTips() does close the tip pop-up window,
the exposed region will not be redrawn until the exposure event has run its course.
void GetRegion(long include_border,long *rx,long *ry,long *rsx,long *rsy,long subx,long suby,long subsx,long subsy)
void GetRegion(long include_border,long *rx,long *ry,long *rsx,long *rsy)
Gets the region the widget will occupy into origin
rx, ry and size rsx, rsy.
An optional sub-geometry of origin subx, suby and
size subsx, subsy can be specified.
These resultant value differs from GetGeometry()
in that it takes into account any space taken by
SetAnnotationSize().
If include_border is non-zero,
the space consumed by the border is included for a potentially larger region.
long InRegion(EW_Event *event,long include_border,long subx,long suby,long subsx,long subsy)
long InRegion(EW_Event *event,long include_border)
Returns TRUE if the specified event
occurs within the region of the widget.
As with GetRegion(), an optional sub-geometry
subx, suby, subsx, subsy and include_border
can be specified.
void SetTieList(WDS_TieList *set)
WDS_TieList *GetTieList(void)
Set/Get the current tie list.
Tie lists allow attributes of otherwise independent widgets to be linked.
If NULL (the default), the widget is not tied.
Derived widgets can be programmed to use the tie by replacing
the virtual member
void TieValuesChanged(WDS_TieValues *tievalues)
which recieves changes in the tie and by calling
void ChangeTieValues(WDS_TieValues *tievalues)
to change the values in the tie.
Care should be taken, though,
because if TieValuesChanged() calls ChangeTieValues(), a loop can occur.
void SetLabel(char *string)
char *GetLabel(void)
WDS_String *GetLabelString(void)
Set/Get the text that appears through some widgets such as on buttons
or divider tabs.
void SetImage(long for_state,WDS_Image *set)
Set an image to to draw for a given state.
void GetMaxImageSize(long *x,long *y)
For a states, get the maximum dimensions for the correspondingly set images.
virtual void SuggestPrefSize(long prefx,long prefy)
Called by widgets to suggest a new prefered size when it believes
a user action directly desires a change.
Undiscretionally calling SetPrefSize()
on some widgets can be disruptive
(such as permanently shrinking buttons),
and the pref size of an EW_Resize
is ignored if the widget has its own pref size.
virtual void DumpString(void)
virtual void DumpInfo(long level)
Replaces virtuals of EW_Widget for printing widget information.
void RegisterEventBypass(long on,EW_Event *event,long bypassflags,long shallowest)
Register or DeRegister a bypass for an on of TRUE or FALSE, respectively.
A bypass matching event with the appropriate bypassflags
is registered/deregistered with an ancestral scope, if found.
If shallowest is non-zero, the least ancestral scope is used.
Otherwise, the most ancestral scope is used.
void SetLocalElement(long state,long attribute,long set)
Calls GetLocalLook()->SetElement(state,attribute,set).
long GetLocalElement(long state,long attribute)
Returns GetLocalLook()->GetElement(state,attribute).
WDS_Widget changes the default event mask defined in EW_Widget
to use a source of EW_EVENT_COMMON|EW_EVENT_FOCUS.
EW_EVENT_COMMON is currently defined as
EW_EVENT_MOUSEPOSITION | EW_EVENT_MOUSEBUTTON | EW_EVENT_KEYBOARD | EW_EVENT_WIDGET | EW_EVENT_APPLICATION.
WDS_WIDGET_FLAGS_AUTOSIZE prevents uniformity under WDS_Form.
WDS_WIDGET_FLAGS_AUTOPREF works well with uniformty.
WDS_WIDGET_FLAGS_AUTOPREF may not work well for a widget as a child of a WDS_Partition
in the direction of partitioning. WDS_Partition may not recognize it as fixed.
WDS_WIDGET_FLAGS_AUTOSIZE should work well with partitioning.