WDS_Popup is not the popped up widget itself, but is the widget that pops
and unpops a window based on mouse events.
In order to work properly, a WDS_Popup requires a WDS_Scope ancestor,
preferably a most ancestral (deepest) one that covers the whole window.
The WDS_Popup automatically registers itself with
it's deepest ancestral scope when necessary.
Note that the WDS_Popup also locates a potentially different
shallowest ancestral scope it uses in an exclusion mechanism for the
WDS_POPUP_SIBLING_HANDOFF flag described below.
It does not matter whether these scopes are the same or different.
The popped up window is an EW_Window.
One of the first child widgets of this window is a WDS_PopupBase.
When the proper event (a button press with the button specified by SetItem())
for popping up a window hits WDS_Popup,
a window is popped up with a WDS_Scope widget and
a WDS_PopupBase widget.
The window is created but is not mapped in the WDS_Popup constructor,
therefore valid handles are available for the popup window and
WDS_PopupBase widget through the member functions
GetBaseWindow() and GetBaseWidget().
With these handles the popup window and widgets themselves may be configured,
presumably before being popped, at least partially.
void SetWindowTitle(char *set)
char *GetWindowTitle(void)
Set/Get the window title.
void SetWindowFlags(long set)
long GetWindowFlags(void)
Set/Get the window flags passed to the popup window when opened.
This is generally preset to a proper value upon widget construction.
void SetPopItem(long set)
long GetPopItem()
void SetUnPopItem(long set)
long GetUnPopItem()
void SetTearItem(long set)
long GetTearItem()
void SetUnTearItem(long set)
long GetUnTearItem()
Set/Get the mouse button(s) that will operate the WDS_Popup widget.
Settings for pop and tear-off operations are specified independently,
as well as the doing and undoing of the pop and tear actions.
This setting is used as the item mask for an EW_Event.
Acceptable values (which may be OR'ed together) are:
| EW_ITEM_LEFT | The left mouse button |
| EW_ITEM_MIDDLE | The middle mouse button |
| EW_ITEM_RIGHT | The right mouse button |
The current default value is EW_ITEM_RIGHT.
void SetFlags(long set)
void SetFlagsIncluding(long set)
void SetFlagsExcluding(long set)
long GetFlags(void)
Set/Get the configuration flags for the widget.
The calls
SetFlagsIncluding() and SetFlagsExcluding()
can selectively set/clear the bits in set.
The valid values (which may be ORed together) are:
| WDS_POPUP_GRAB_POINTER |
When a window is popped up the pointer will be grabbed and
all mouse events will go to the WDS_Popup
widget until the window is popped back down.
Events will be routed to the popped up window when necessary.
|
| WDS_POPUP_SIBLING_HANDOFF |
When the mouse is dragged with the button pressed and a window popped into a
WDS_Popup widget that is a sibling to the WDS_Popup
widget that popped up the current popup window,
the current popup window is unpopped and the
sibling's popup window is popped up. This only works if the
WDS_POPUP_GRAB_POINTER flag is also set.
Note that previously, this use of the word sibling referred to any
widget of the same parent.
Popup functionality has changed to use ancestral scope registration
as an exclusion mechanism,
so the handoff can occur from any like-configured widget
using the same shallowest ancestral scope.
|
| WDS_POPUP_AUTOPOP |
If the mouse is dragged with the button pressed and a window popped into
a descendent WDS_Popup widget that is in the popped up window,
the descendent's popup window is also popped. This only works if the
WDS_POPUP_GRAB_POINTER is also set.
|
| WDS_POPUP_NONSTICK |
If the button is released while the mouse is in the WDS_Popup
widget with its window popped up, then the popped up window is unpopped.
Without this flags set,
the popup window would remain if the button was released while
the mouse was in the WDS_Popup widget.
|
| WDS_POPUP_PERSISTANT |
When the button is released after the window has been popped up the window
remains popped up. If WDS_POPUP_GRAB_POINTER has been set, the pointer will
be released even though the window is still popped up.
|
| WDS_POPUP_BUTTONLESS_POP |
Allows the popup to Pop() if another popup has popped and
registered as such with the same ancestral scope.
This functionality also requires the popup's look element
WDS_ELEMENT_POPUP_IDLE_HANDOFF to be interpreted as TRUE.
|
void SetLocation(long location)
long GetLocation()
Set/Get the location in which to pop up the popup window.
The popup window will be located on
the screen based on the location setting adjusted by the location offsets.
The valid values are:
| WDS_POPUP_LOC_MOUSE |
The upper left corner of the popup window is set to the current mouse
location.
|
| WDS_POPUP_LOC_BOTTOM |
The upper left corner of the popup window is set to the lower left corner
of the WDS_Widget.
|
| WDS_POPUP_LOC_RIGHT |
The upper left corner of the popup window is set to the upper right corner
of the WDS_Widget.
|
| WDS_POPUP_LOC_TOP |
The lower left corner of the popup window is set to the upper left corner
of the WDS_Widget.
|
| WDS_POPUP_LOC_LEFT |
The upper right corner of the popup window is set to the upper left corner
of the WDS_Widget.
|
| WDS_POPUP_LOC_FROM_REGION |
An OR'able flag which causes the location to be assigned relative
to the region obtained from WDS_Widget::GetRegion()
instead of the full geometry obtained from WDS_Widget::GetGeometry().
|
If the popup window location does not map completely onto the screen, the
location is adjusted so that it will (if possible).
void SetOffset(long x, long y)
void GetOffset(long *x, long *y)
Set/Get the popup window location offset. The popup window will be located on
the screen based on the location setting adjusted by the location offsets.
void Pop(EW_Event *event)
void Drop(void)
Manually pop/unpop a WDS_Popup.
The event, optionally NULL,
is used for mouse location and can also be sent to a state-change callback.
void TearOff(void)
void UnTearOff(void)
Manually cause or counter a tear-off operation.
long GetTorn(void)
Returns non-zero if the popup window is currently torn.
void SetPopBlock(long set)
long GetPopBlock(void)
Set/Get popup blocking.
When non-zero, the member Pop() will not pop the popup window.
Pop() is still called by Operate(), but with altered behavior.
Note that scope registration and state change callbacks can still occur.
WDS_PopupBase *GetBaseWidget()
Get a pointer to the base widget in the popup window.
EW_Window *GetBaseWindow()
Get a pointer to the popup window.
| WDS_STATE_0 | Drop/UnTear |
| WDS_STATE_1 | Pop/Tear |